Versions Compared

Old Version 2

changes.mady.by.user Daniel CHENG

Saved on

compared with

New Version Current

changes.mady.by.user Gabriel BERLICKI

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Section


Column

Background

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

...

modernise 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

...

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.

Note
titleMutual TLS authentication

The other tls_client_auth and self_signed_tls_client_auth authentication methods defined in the FAPI part 2 standard leverages mutual TLS which necessitates tailored backend servers infrastructure. They are not proposed for DAS API authentication due the non-negligible additional costs and complexity that they will generate . 

 

...

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.

    draw.io Diagram
    bordertrue
    diagramNameWIPO authorization server
    simpleViewerfalse
    width600
    linksauto
    tbstyletop
    lboxtrue
    diagramWidth721
    revision1


  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.

    draw.io Diagram
    bordertrue
    diagramNameMutual authorization servers
    simpleViewerfalse
    width600
    linksauto
    tbstyletop
    lboxtrue
    diagramWidth641
    revision1

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.

draw.io Diagram
bordertrue
diagramNameprivate_key_jwt registration
simpleViewerfalse
width600
linksauto
tbstyletop
lboxtrue
diagramWidth1081
revision2

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.

Code Block
languagebash
themeRDark
titleprivate_key_jwt generation script
collapsetrue
#!/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}"

...

Files

...

Description

...

private_key_jwt authentication process

The authentication flow of private_key_jwt is depicted in the diagram below

draw.io Diagram
bordertrue
diagramNameprivate_key_jwt authentication
simpleViewerfalse
width600
linksauto
tbstyletop
lboxtrue
diagramWidth1121
revision1

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

...

Attribute

...

Example

...

Description

...

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

...

{
  "alg": "ES256",
  "typ": "JWT"
}

...

{
  "iss": "das-api-auth",
  "sub": "das-api-auth",
  "aud": "https://logindev.wipo.int:443/am/oauth2/access_token",
  "exp": 1622450728
}

...

# Signature of the header and payload sections. # it is an array of bytes encoded in base 64

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

private_key_jwt assertion

...

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkYXMtYXBpLWF1dGgiLCJzdWIiOiJkYXMtYXBpLWF1dGgiLCJhdWQiOiJodHRwczovL2xvZ2luZGV2LndpcG8uaW50OjQ0My9hbS9vYXV0aDIvYWNjZXNzX3Rva2VuIiwiZXhwIjoxNjIyNDUwNzI4fQ.BLA6k2kKKFVm6AG-DPDpRU_5JDFGRF1dHjKul7saWCv5OxXGg4EY-J9e1p8Dg0ngD2dZ2grkJ2su7jaHy67YEw

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:

...

POST parameter

...

example

...

Description 

...

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkYXMtYXBpLWF1dG giLCJzdWIiOiJkYXMtYXBpLWF1dGgiLCJhdWQiOiJodHRwczovL2xvZ2luZG V2LndpcG8uaW50OjQ0My9hbS9vYXV0aDIvYWNjZXNzX3Rva2VuIiwiZXh wIjoxNjIyNDUwNzI4fQ.BLA6k2kKKFVm6AG-DPDpRU_5JDFGRF1dHjKul7saWCv5OxXGg4EY-J9e1p8Dg0ngD2dZ2grkJ2su7jaHy67YEw

...

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.

Code Block
themeRDark
titleprivate_key_jwt authentication script
collapsetrue
#!/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": "eyJ0eXAiOiJKV1QiLCJraWQiOiJmVWRmbEJSa3c5bm1tejcrL3BmMWM5d2RYdXc9IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJkYXMtYXBpLWF1dGgiLCJjdHMiOiJPQVVUSDJfU1RBVEVMRVNTX0dSQU5UIiwiYXVkaXRUcmFja2luZ0lkIjoiMTQyYjMwODEtZDNjNy00MjJjLWI4ZDQtNjU4NjkwNjVmMzQ4LTU0OTkxIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbmRldi53aXBvLmludDo0NDMvYW0vb2F1dGgyIiwidG9rZW5OYW1lIjoiYWNjZXNzX3Rva2VuIiwidG9rZW5fdHlwZSI6IkJlYXJlciIsImF1dGhHcmFudElkIjoibko4bmh5bEM4S3g5RFk4bDJTSGxvcHdDZmJnIiwiYXVkIjoiZGFzLWFwaS1hdXRoIiwibmJmIjoxNjIyNDU0OTUzLCJncmFudF90eXBlIjoiY2xpZW50X2NyZWRlbnRpYWxzIiwic2NvcGUiOlsiZGFzLWFwaS9kYXMtYWNjZXNzIl0sImF1dGhfdGltZSI6MTYyMjQ1NDk1MywicmVhbG0iOiIvIiwiZXhwIjoxNjIyNDU4NTUzLCJpYXQiOjE2MjI0NTQ5NTMsImV4cGlyZXNfaW4iOjM2MDAsImp0aSI6InJvRzhtcWE4WjFaM0YwME1kMjB2VW95aEEwSSJ9.d1EEdioprD2AxQxQcVj0zlN8hvSaIdtub0Lk887m52qEKFt9YiW3uGhpw8bMnhwsUyBbbdFq1flA3pVdKYAdNhQ2dRBIemTH8_NjA4l4giGpLeKJ7WRQA-ldsWrrLkLkVu7gbx7TmMLrTkXgL17kiLdPQ44S1O6LKX52v3KkT0XYEyMYIuzYlnMBs1GQWkoJEALZVIH3TtaAG22o4dxlCcMVxUCo-SyOctjRkfmLvuKEXpDvAG2F93o61Mz1sOtSC2m6nBQA9zd3MxtNd5vd0791QH16Of53IozPj7jRXblYCYq9SJyXzdHN7IEJWrT7C1vvwFVnq8c8QArKsMmgBw",
  "scope": "das-api/das-access",
  "token_type": "Bearer",
  "expires_in": 3599
}

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 

...

{
  "sub": "das-api-auth",
  "cts": "OAUTH2_STATELESS_GRANT",
  "auditTrackingId": "142b3081-d3c7-422c-b8d4-65869065f348-54991",
  "iss": "https://logindev.wipo.int:443/am/oauth2",
  "tokenName": "access_token",
  "token_type": "Bearer",
  "authGrantId": "nJ8nhylC8Kx9DY8l2SHlopwCfbg",
  "aud": "das-api-auth",
  "nbf": 1622454953,
  "grant_type": "client_credentials",
  "scope": [
    "das-api/das-access"
  ],
  "auth_time": 1622454953,
  "realm": "/",
  "exp": 1622458553,
  "iat": 1622454953,
  "expires_in": 3600,
  "jti": "roG8mqa8Z1Z3F00Md20vUoyhA0I"
}


Column

Children Display

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.

...

Source

...

DAS Digital Library

Stored for unlimited period of time in private encrypted S3 storage

...

In TRANSIT

Available in private encrypted S3 storage only during the time of the document exchange

...

PCT priority documents originated from offices other than RO/IB

...

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) 

...

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) 

...

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

draw.io Diagram
bordertrue
diagramNameDocuments-hosted-by-OFF
simpleViewerfalse
linksauto
tbstyletop
lboxtrue
diagramWidth697
revision5

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) 

...