API Security for Berlin

PSP Certificate registration

An authorization of PSP has to be approved/rejected by the National Competent Authority (NCA) that is responsible for payment services in their country. Following are the steps of PSP certificate registration.

1. PSP submits a certificate that needs to be registered to Trusted Service Provider (TSP) with the required documentation including the PSD2 specific attributes. For more information on the attributes that WSO2 Open Banking solution validates, refer PSD2 certificate specific attributes validation.

2. The TSP performs an identity validation as required by its certificate policy.

3. The TSP validates PSD2 specific attributes using the information provided by NCA.

4. The TSP issues the qualified certificate in compliance with the profile requirements given by the PSU.

5. PSP receives the certificate that is now approved by NCA.

   

Certificate revocation validation

WSO2 Open Banking solution uses two types of certificates. Namely, Certificates for Website Authentication (QWAC) and Certificates for Electronic Seals (QsealC) that are trusted certificates by ensuring the validity against certificate status services. Certificate status services are Online Certificate Status Protocol (OCSP) and Certificate Revocation List (CRL) provided by the TSP. A revocation can happen through a qualified TSP or a revocation request can originate from the NCA, which has authorized or registered the payment service provider.

Below diagram shows how the TSP revokes the certificate.

• Update the axis2.xml file

<module ref="mtlscertvalidator"/

• Update the open-banking.xml file

Add the following configurations under the Server root element in the <WSO2_OB_APIM_Home>repository/conf/finance/open-banking.xml file.

<CertificateManagement>

<!-- Enable sending client cert as a transport header when TLS is terminated before reaching
Gateway-->
<ClientTransportCertAsHeaderEnabled>true</ClientTransportCertAsHeaderEnabled>

<!-- Validate the issuer of the certificate when the client cert is received as a transport header-->
 <TransportCertIssuerValidationEnabled>true</TransportCertIssuerValidationEnabled>

<!--Set the value of the transport certificate header sent in the request if MTLS is terminated
before the gateway. Default value is ssl.client.auth.cert.X509-->
<TransportCertificateHeader>ssl.client.auth.cert.X509</TransportCertificateHeader>

<!-- Expiry time for the cache (in seconds) for storing the validation result of the certificates-->
<ClientCertificateCacheExpiry>3600</ClientCertificateCacheExpiry>

<!-- Enable certificate OCSP and CRL validation --> <CertificateRevocationValidationEnabled>false</CertificateRevocationValidationEnabled>

<!--Manager class implementation responsible for verifying certificate revocation status-->
<RevocationValidationManagerImplClass>com.wso2.finance.open.banking.mtlscert.validator.service.CertRevocationValidationManagerImpl</RevocationValidationManagerImplClass>

<!-- Retry count for validating certificate OCSP and CRL revocation status -->
<CertificateRevocationValidationRetryCount>3</CertificateRevocationValidationRetryCount>

<!-- List of issuer DNs whose issued certificates needs to be skipped from certificate revocation
validation. e.g. <IssuerDN>CN=Test Pre-Production Issuing CA, O=Test, C=GB</IssuerDN> -->
<RevocationValidationExcludedIssuers>
<IssuerDN></IssuerDN>
</RevocationValidationExcludedIssuers>

<!--Truststore dynamic loading interval (in seconds). Default value has been set to 86400 seconds-->
<TrustStoreDynamicLoadingInterval>86400</TrustStoreDynamicLoadingInterval>

</CertificateManagement>

Certificates for Website Authentication (QWAC)

QWAC is used to secure communication by identifying and authenticating the communicating parties. Parties involved in the communication who are identified and authenticated by QWAC:

• Payment initiation service providers (PISP)
• Account information service providers (AISP)
• Payment service providers issuing card-based payment instruments (PIISP)
• Account servicing payment service providers (ASPSP)

QWAC must be used to establish a secure TLS channel and protect the communication (in the transport layer) from potential attackers on the network. QWAC ensures the person or the system connecting to the website. But it cannot prove the legally assumed evidence of a transaction to the third party.

The WSO2 Open Banking validates roles of TPP (Third Party Providers) according to the PSD2. During an API call, this validation restricts TPPs accessing APIs if the roles are not mentioned in eIDAS QWAC (Transport layer certificate). The validation checks following aspects of the eIDAS QWAC.

1.  If the certificate is technically correct and has not expired.
2. If the certificate is qualified. 
3. If the certificate contains the required PSD2 information. (i.e., PSD roles, Authorization Number, NCA etc.)
4. If the certificate has not been revoked since it was issued by using CRL or OCSP checks.

Steps below describe how to enable the eIDAS QWAC validations during API calls.

Step 1

Download the latest WUM product for the WSO2 Open Banking API Manager instance. For WUM instructions, see WUM Updates.

Add the following configurations to the velocity-template.xml file in the <WSO2_OBAM_HOME>/repository/resources/api_templates/velocity_template.xml in order to enable ClientCertValidationHandler.

<handler class="com.wso2.finance.open.banking.gateway.berlin.ClientCertValidationHandler">
         <property name="certificateAsHeader" value="true"/>
         <property name="psd2Role" value="$apiObj.additionalProperties.get('psd2Role')"/>
</handler>

Step 3

Log in to API Publisher as a publisher at https://<WSO2_OBAM_HOST>:9443/publisher.

• Click Edit on the existing API.

• Click Manage.

• Click API Properties and enter values under property: psd2Role. See the table below to find the TPP roles for the respective APIs.

Step 4

Restart the WSO2 Open Banking API Manager instance and try API calls with the certificates.

Certificates for Electronic Seals (QsealC)

QsealCs is used to provide evidence with a legal assumption of authenticity (including identification and authentication of the source) and integrity of a transaction. QsealC ensures the application layer security to protect the data or messages from potential attackers during or after the communication. The receiver of the sealed data can determine who sealed the data. This can also be proven to a third party even after the communication has ended. The evidence of the transaction can be provided by QsealC with legal assumption and can protect the authenticity and integrity of data when relayed through third parties.

A certificate can be either for website authentication or electronic seals, but not both. Therefore, these two types of certificates are not interchangeable. The following diagram elaborates on the flow followed by WSO2 on extracting the certificate through the request header and invoking the URLs provided in the certificate extension for CRL and OCSP. Confirm the validity of a certificate by analyzing the response status. The information about OCSP and CRL are included in the certificate as extensions.

Validating PSD2 authorization number/identifier identified by the NCA

A PSD2 authorization number or an identifier is recognized by the NCA by placing it as organizationIdentifier attribute under the subject name field in the QsealC certificate. An authorization number can form a structure including:

• Legal person identity type reference

• Country code that represents the NCA country

• NCA identifier and PSP identifier

If the authorization number is not issued by the NCA, then another identifier that is recognized by NCA is used as the organizationIdentifier.

Validating Role of the PSP

The role of the PSP is declared by NCA via their public registry. The PSP may contain one or more of the following roles.

1. Account Servicing Payment Service Provider (ASPSP)

2. Payment Initiation Service Provider (PISP)

3. Account Information Service Provider (AISP)

4. Payment Service Provider issuing Card-Based Payment Instruments Issuer (CBPII)

Each role is represented by a role identifier and a role name. Any other role that is not defined, has to be defined and registered by an EU recognized organization. WSO2 Open Banking solution validates the role by validating the Object Identifier (OID) attributes to make sure that the registered role is passed through the certificate. OID attributes are stored in QCStatement within the QCstatements extension.

Validating Issuer of the certificate

The name and the identifier of the competent authority are also validated to ensure the issuer of the certificate.