New DAS exchange API

Both of the automated interfaces currently in use (TDA and SFTP) depend on older technologies. The future DAS service should be upgraded to a more modern technology, which will simplify the implementation for offices, improve security and authentication mechanisms, and potentially allow for faster document exchange.

A new REST API is proposed to modernize the automated interfaces between offices and WIPO DAS:

• REST Web Services., OpenID Connect and asymmetric encryption for unpublished document content to secure the exchange process and content
• Please click here to download the specification in yaml

API Security

For advanced API Security, the FAPI (Financial grade API) – Part 2 standard adds an extra-layer on top of OAuth2.0 and OIDC.

1. private_key_jwt, if the client sends its credentials as a JWT.
2. tls_client_auth, if the client uses a CA-signed certificate for mutual TLS authentication.
3. self_signed_tls_client_auth, if the client uses a self-signed certificate for mutual TLS authentication. 

Access control implementation

To allow safe, secure and trustable authentication, DAS API will have to implement one of the authentication permitted by FAPI part 2. In order not to the implementation of the backend infrastructure too complex, the proposed implementation will only support the private_key_jwt authentication method. The private_key_jwt authentication is based on the asymmetric key signature of the login information, those details – login info + signature - are sent to the authorization server which returns an access token if valid. The access token can then be used to call the DAS API.

The following controls must be enforced to guaranty the same level of security than the TDA VPN connection

Network access-control

Decrease the threat surface and avoid data exfiltration:

1. Restrict communication between WIPO and IP Offices with white listed IP addresses
2. Perform egress/ingress filtering on the approved protocols to avoid data exfiltration.
3. Achieve non-disclosure countermeasure and information protection in transit by enabling TLS1.2 encryption.

API mandatory controls 

Protect access to API

1. API DDOS protection
2. API –Threat protection

Possible setups

DAS protocol necessitates bi-directional communication between offices and WIPO, in practical terms it means that offices must also support private_key_jwt authentication. To ease integration and give freedom to office to choose, we propose two possible setups:

1. WIPO authorization server setup

   Office will use the WIPO authorization server infrastructure for authentication:
   Inbound traffic: whenever a call is received from the WIPO central DAS service the office will have to contact and verify the token against the WIPO authorization server.
   Outbound traffic: office will authenticate using its client id registered in WIPO authorization server and will use the returned access_token to call the WIPO DAS API.
   
   
   eyJleHRTcnZJbnRlZ1R5cGUiOiIiLCJnQ2xpZW50SWQiOiIiLCJjcmVhdG9yTmFtZSI6IkRhbmllbCBDSEVORyIsIm91dHB1dFR5cGUiOiJibG9jayIsImxhc3RNb2RpZmllck5hbWUiOiJEYW5pZWwgQ0hFTkciLCJsYW5ndWFnZSI6ImVuIiwiZGlhZ3JhbURpc3BsYXlOYW1lIjoiIiwic0ZpbGVJZCI6IiIsImF0dElkIjoiMTAyNTYwNjAyNSIsImRpYWdyYW1OYW1lIjoiV0lQTyBhdXRob3JpemF0aW9uIHNlcnZlciIsImFzcGVjdCI6IiIsImxpbmtzIjoiYXV0byIsImNlb05hbWUiOiJOZXcgREFTIGV4Y2hhbmdlIEFQSSIsInRic3R5bGUiOiJ0b3AiLCJjYW5Db21tZW50IjpmYWxzZSwiZGlhZ3JhbVVybCI6IiIsImNzdkZpbGVVcmwiOiIiLCJib3JkZXIiOnRydWUsIm1heFNjYWxlIjoiMSIsIm93bmluZ1BhZ2VJZCI6MTAyNTYwNTk5MywiZWRpdGFibGUiOmZhbHNlLCJjZW9JZCI6MTEyMTAyNjA4MywicGFnZUlkIjoiIiwibGJveCI6dHJ1ZSwic2VydmVyQ29uZmlnIjp7ImVtYWlscHJldmlldyI6IjEifSwib2RyaXZlSWQiOiIiLCJyZXZpc2lvbiI6MSwibWFjcm9JZCI6ImRkNjQ4Y2ZjLWJhMDgtNGU5My04NDFmLTVmOWU5MmU1NDVlOCIsInByZXZpZXdOYW1lIjoiV0lQTyBhdXRob3JpemF0aW9uIHNlcnZlci5wbmciLCJsaWNlbnNlU3RhdHVzIjoiT0siLCJzZXJ2aWNlIjoiIiwiaXNUZW1wbGF0ZSI6IiIsIndpZHRoIjoiNjAwIiwic2ltcGxlVmlld2VyIjpmYWxzZSwibGFzdE1vZGlmaWVkIjoxNjI0NjU3MDIzOTY3LCJleGNlZWRQYWdlV2lkdGgiOmZhbHNlLCJvQ2xpZW50SWQiOiIifQ==
   
   

   
   

2. Mutual authorization server setup

   Office wants to take care of the authentication by itself consequently provides the private_key_jwt authentication.
   Inbound traffic: The WIPO central DAS service will authenticate against a client id registered in the office authorization server and will use the returned access_token to call the office DAS API 
   Outbound traffic: office will authenticate using its client id registered in WIPO authorization server and will use the returned access_token to call the WIPO DAS API.
   
   
   eyJleHRTcnZJbnRlZ1R5cGUiOiIiLCJnQ2xpZW50SWQiOiIiLCJjcmVhdG9yTmFtZSI6IkRhbmllbCBDSEVORyIsIm91dHB1dFR5cGUiOiJibG9jayIsImxhc3RNb2RpZmllck5hbWUiOiJEYW5pZWwgQ0hFTkciLCJsYW5ndWFnZSI6ImVuIiwiZGlhZ3JhbURpc3BsYXlOYW1lIjoiIiwic0ZpbGVJZCI6IiIsImF0dElkIjoiMTAyNTYwNjAyNyIsImRpYWdyYW1OYW1lIjoiTXV0dWFsIGF1dGhvcml6YXRpb24gc2VydmVycyIsImFzcGVjdCI6IiIsImxpbmtzIjoiYXV0byIsImNlb05hbWUiOiJOZXcgREFTIGV4Y2hhbmdlIEFQSSIsInRic3R5bGUiOiJ0b3AiLCJjYW5Db21tZW50IjpmYWxzZSwiZGlhZ3JhbVVybCI6IiIsImNzdkZpbGVVcmwiOiIiLCJib3JkZXIiOnRydWUsIm1heFNjYWxlIjoiMSIsIm93bmluZ1BhZ2VJZCI6MTAyNTYwNTk5MywiZWRpdGFibGUiOmZhbHNlLCJjZW9JZCI6MTEyMTAyNjA4MywicGFnZUlkIjoiIiwibGJveCI6dHJ1ZSwic2VydmVyQ29uZmlnIjp7ImVtYWlscHJldmlldyI6IjEifSwib2RyaXZlSWQiOiIiLCJyZXZpc2lvbiI6MSwibWFjcm9JZCI6IjhlMzM0ZGJhLWE0YWItNGNmYy05OGQ3LTQyN2NhMmRkM2Q0NSIsInByZXZpZXdOYW1lIjoiTXV0dWFsIGF1dGhvcml6YXRpb24gc2VydmVycy5wbmciLCJsaWNlbnNlU3RhdHVzIjoiT0siLCJzZXJ2aWNlIjoiIiwiaXNUZW1wbGF0ZSI6IiIsIndpZHRoIjoiNjAwIiwic2ltcGxlVmlld2VyIjpmYWxzZSwibGFzdE1vZGlmaWVkIjoxNjI0NjU3MDgyMzA2LCJleGNlZWRQYWdlV2lkdGgiOmZhbHNlLCJvQ2xpZW50SWQiOiIifQ==

Initial private_key_jwt registration process

The private_key_jwt authentication is based on asymmetric key, the private part is generated and only known by the client whereas the public part is communicated and registered in the authorization server for the specific client.

Generation of ES256 asymmetric keys

openssl command can be used to generate ES256 asymmetric keys as required by the FAPI part 2 specification. Office will keep the private key and share the public key for registration with WIPO. Below is an example of script to generate ES256 asymmetric keys.

#!/bin/bash
# Set the environment
PRIVATE_KEY_ES256=es256_private.pem
PUBLIC_KEY_ES256=es256_public.pem
CLIENT_NAME=DAS
 
# Generates the ES256 keys
openssl ecparam -genkey -name prime256v1 -noout -out "${PRIVATE_KEY_ES256}"
 
# Extracts the public key
openssl ec -in "${PRIVATE_KEY_ES256}" -pubout -out "${PUBLIC_KEY_ES256}"
 
# Generates an x509 certificate 
CERT_KEY_ES256=es256_cert.pem
OPENSSL_CONF=./openssl.cnf
CERT_CN="${CLIENT_NAME} private_key_jwt authentication"
# Build the certificate config file  
printf '[ req ]\n' > "${OPENSSL_CONF}"
printf 'prompt = no\n' >> "${OPENSSL_CONF}"
printf 'distinguished_name = req_distinguished_name\n' >> "${OPENSSL_CONF}"
printf '[ req_distinguished_name ]\n' >> "${OPENSSL_CONF}"
printf 'CN = %s\n' "${CERT_CN}" >> "${OPENSSL_CONF}"
# Creates the x509 certificate 
openssl req -x509 -new -config "${OPENSSL_CONF}" -key "${PRIVATE_KEY_ES256}" -out "${CERT_KEY_ES256}"

The following files are examples:

private_key_jwt authentication process

The authentication flow of private_key_jwt is depicted in the diagram below

The private_key_jwt authentication consists of creating a JSON structure containing the following login attributes:

ES256 signing algorithm + above attributes + signature of them must be served in JWT format (rfc7519), see below:
JWT client assertion header

JWT client assertion payload

JWT client assertion signature

All parts are encoded and separated by '.' to make up the JWT as follows

private_key_jwt assertion

The JWT client assertion can now be submitted to authorization server for authentication with the token endpoint (i.e. POST https://logindev.wipo.int:443/am/oauth2/access_token in the attached specification) including the following parameters for client_credentials:

Note: The above token endpoint is part of third party product that supports OpenID Connect (OIDC) authentication protocol based on the OAuth 2.0 family of specifications

Below is an example of authentication script.

#!/bin/bash
PRIVATE_KEY_ES256=es256_private.pem
CLIENT_ID=das-api-auth
SCOPE="das-api/das-access"
ISSUER="https://logindev.wipo.int/am/oauth2"
 
# https://logindev.wipo.int/am/oauth2/.well-known/openid-configuration
OIDC_CONFIG_JSON=$(curl -k "${ISSUER}/.well-known/openid-configuration")
 
# Generic way to obtain the token endpoint
TOKEN_ENDPOINT=$(printf '%s' ${OIDC_CONFIG_JSON} | jq -r ".token_endpoint")
 
UTC_TIME=$(date -u +%s)
EXP_TIME=$(expr "$UTC_TIME" + 10)
 
JSON='{'
JSON=${JSON}$(printf '"iss":"%s"' ${CLIENT_ID})
JSON=${JSON}$(printf ',"sub":"%s"' ${CLIENT_ID})
JSON=${JSON}$(printf ',"aud":"%s"' ${TOKEN_ENDPOINT})
JSON=${JSON}$(printf ',"exp":%s' ${EXP_TIME})
JSON=${JSON}'}'
 
JSON_HEADER_B64=$(printf '{"alg":"ES256","typ":"JWT"}' | jq -cj | base64 -w0 | tr -d '\n=' | tr '+/' '-_')
JSON_PAYLOAD_B64=$(printf $JSON | jq -cj | base64 -w0 | tr -d '\n=' | tr '+/' '-_')
JSON_SIGNATURE_ASN1_B64=$(printf '%s.%s' $JSON_HEADER_B64 $JSON_PAYLOAD_B64 | openssl dgst -sha256 -sign "${PRIVATE_KEY_ES256}" | openssl asn1parse -inform DER | base64 -w0)
JSON_SIGNATURE_HEX=$(printf $JSON_SIGNATURE_ASN1_B64 | base64 -d | sed -n '/INTEGER/p' | sed 's/.*INTEGER\s*://g' | sed -z 's/[^0-9A-F]//g')
JSON_SIGNATURE_B64=$(printf $JSON_SIGNATURE_HEX | xxd -p -r | base64 -w0 | tr -d '\n=' | tr '+/' '-_')
 
JWT_ASSERTION=$(printf '%s.%s.%s' $JSON_HEADER_B64 $JSON_PAYLOAD_B64 $JSON_SIGNATURE_B64)
# echo $JWT_ASSERTION
 
# Access token private_key_jwt
curl --insecure \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode scope="${SCOPE}" \
  --data-urlencode "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  --data-urlencode "client_assertion=${JWT_ASSERTION}" \
  --url "${TOKEN_ENDPOINT}"

The output of the script is as follows:

private_key_jwt authentication output

Access_token attributes like signature, validity, audience and scopes must be verified by the client, similarly DAS API must also verify the access_token and must additionally check if the client id (=sub claim) is authorized. DAS API must maintain the whitelisted clients 

access_token payload

Priority document storage in WIPO DAS

Priority documents are classified as 'confidential' with the exception of unpublished documents hosted by the PCT which are classified as 'highly confidential'. As a result, unpublished PCT documents must be stored at WIPO/UNICC facilities, not public cloud. However, this data may transit through public networks and through services hosted on public cloud through an encrypted channel. 

In practical terms, this means that PCT international applications from RO/IB that are used a priority documents cannot be stored in AWS however they can be in transit via AWS services.

Consequently, in DAS framework, any priority documents that are based on RO/IB PCT applications will be accessed in transit only, the rest will be able to be stored in and retrieve from  AWS.

Registration and Retrieval

Documents can be registered by OFF and kept in WIPO DAS

The following diagram describes the exchange flows for registration and retrieval of documents hosted in WIPO DAS by notification to OSF

Figure A: Notification of document availability

Exchange flow to register document

• (1a) - OFF requests a presigned url from WIPO DAS to upload a file identified by a file id (i.e. POST /das/v1/requests/files/url-uploads) 
• (1b) - OFF uploads the document file content using a presigned url given in step (step 1a)
• (1c) - OFF requests document registration to WIPO DAS by referring to the uploaded file content by the corresponding file id (i.e. POST /das/v1/requests/registrations) 

Note: steps (1a) and (1b) are not required if the OFF keeps the actual document file content in its own digital library

Exchange flow to correct filing date or parent application details in which the foreign priority document is held 

• (1c) - OFF requests document registration to WIPO DAS by specifying the new document attributes (i.e. PUT /das/v1/requests/registrations) 

Exchange flow to replace document content for correction purpose 

• (1a) - OFF requests a presigned url from WIPO DAS to upload a file identified by a file id (i.e. POST /das/v1/requests/files/url-uploads) 
• (1b) - OFF uploads the corrected document file content using a presigned url given in step (1a)
• (1c) - OFF requests document registration to WIPO DAS by referring to the uploaded file content by the corresponding file id (i.e. PUT /das/v1/requests/registrations)

Exchange flow to retrieve document hosted in WIPO DAS

• (2a) - OSF sends a document retrieval request to WIPO DAS and receives a request acknowledgement id (i.e. POST /das/v1/requests/retrievals) 
• (2b) - WIPO DAS prepares the requested document for download and notifies the OSF of the document availability (i.e. Figure A) by referring to the request acknowledgement id returned in step (2a) (i.e. POST /das/v1/requests/notifications) 
  Note: Alternatively , OSF may use the check status (i.e. Figure B) to download the document content when it is reported as available by WIPO DAS (i.e. GET /das/v1/requests/retrievals/statuses) 
• (2c) - OSF retrieves file location URL from WIPO DAS to download the document file content (i.e. GET /das/v1/requests/url-downloads). Downloads can be repeated while the requested document is not deleted from WIPO DAS
• (2d) - OSF downloads file from WIPO DAS 
• (2e) - Optionally OSF deletes the download files from the DAS transit zone (i.e. DELETE /das/v1/requests/files) 

Note: if OSF does not delete the downloaded file, WIPO DAS will delete it after a pre-defined period (e.g. 1 week)

The following diagram describes the exchange flows for registration and retrieval of documents hosted in WIPO DAS and the OSF checking on regular basis statuses of retrievals requests

Figure B: OSF checking document availability

Documents registered and kept in the OFF digital library

The following diagram describes the exchange flows for registration and retrieval of documents hosted in OFF

Exchange flow to retrieve document from the OFF digital library

1. OSF sends a document retrieval request to WIPO DAS and receives a request acknowledgement id issued by WIPO DAS (i.e. POST /das/v1/requests/retrievals) 
2. WIPO DAS forwards the retrieval request to the OFF (i.e. POST /das/v1/requests/retrievals) 
3. OFF prepares the requested document for download and notify WIPO DAS of the document availability by referring to the request acknowledgement id returned by WIPO DAS (i.e. POST /das/v1/requests/notifications) 
4. WIPO DAS retrieves the file location URL based on  (i.e. GET /das/v1/requests/files/url-downloads)
5. WIPO DAS download the document file content from OFF
6. WIPO DAS prepares the requested document for download by OSF and notifies the OSF of the document availability by referring to the request acknowledgement id returned in step 1 (i.e. POST /das/v1/requests/notifications) 
7. OSF retrieves the file location URL for document download by referring to the request acknowledgement id returned in step 1 (i.e. GET /das/v1/requests/files/url-downloads)
8. OSF uses the given file location URL obtained in step 7 to download the document file content
9. Optionally OSF deletes the download files from the DAS transit zone (i.e. DELETE /das/v1/requests/files) 

Note: if OSF does not delete the downloaded file, WIPO DAS will delete it after a pre-defined period (e.g. 1 week)

Documents can be registered by OFF using WIPO DAS as transit zone to exchange big-sized documents

The following diagram describes the exchange flows for registration and retrieval of documents hosted in OFF but big-sized documents can be transmitted through the DAS transit zone

Exchange flow to retrieve document transmitted by OFF to WIPO DAS transit zone

1. OSF sends a document retrieval request to WIPO DAS and receives a request acknowledgement id issued by WIPO DAS (i.e. POST /das/v1/requests/retrievals) 
2. WIPO DAS forwards the retrieval request to the OFF and receives a request acknowledgement id issued by OFF (i.e. POST /das/v1/requests/retrievals) 
3. OFF requests a presigned url from WIPO DAS to upload a file and receives the file id from WIPO DAS (i.e. POST /das/v1/requests/url-uploads)
4. OFF uploads the requested document file content into DAS transit zone using a presigned url given in step 3
5. OFF updates the retrieval file id in WIPO DAS by referring to the request acknowledgement id issued by OFF (i.e. PUT /das/v1/requests/retrievals)
6. OFF notifies WIPO DAS of the document availability by referring to the request acknowledgement id returned in step 2 (i.e. POST /das/v1/requests/notifications) 
7. WIPO DAS prepares the requested document for download by OSF and notifies the OSF of the document availability by referring to the request acknowledgement id returned in step 1 (i.e. POST /das/v1/requests/notifications) 
8. OSF retrieves the file location URL to download the document file content by referring to the request acknowledgement id returned in step 1 (i.e. GET /das/v1/requests/files/url-downloads)
9. OSF downloads the file using the URL obtained in step 8
10. Optionally OSF deletes the download file from the DAS transit zone (i.e. DELETE /das/v1/requests/files) 

Note: if OSF does not delete the downloaded file, WIPO DAS will delete it after a pre-defined period (e.g. 1 week)