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:
For advanced API Security, the FAPI (Financial grade API) – Part 2 standard adds an extra-layer on top of OAuth2.0 and OIDC.
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 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:
Protect access to API
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:
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.
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:
Files | Description |
|---|---|
| es256_cert.pem | Certificate file that will be communicated to WIPO for the configuration of the private_key_jwt client authentication |
| es256_private.pem | Must never be communicated and kept secret, used by the client to sign the private_key_jwt authentication request |
| es256_public.pem | Used only at the generation step, kept for record |
| openssl.cnf | Used only at the generation step, kept for record |
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:
Attribute | Example | Description |
|---|---|---|
| iss | das-api-auth | Issuer: Client id |
| sub | das-api-auth | Subject: Client id |
| aud | https://logindev.wipo.int:443/am/oauth2/access_token | Audience: Token endpoint of the authorization server |
| exp | 1622450728 | Expiration time: The expiration time of the data, current time + small amount of seconds (current epoch + 10s is ok) |
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:
POST parameter | example | Description |
|---|---|---|
| grant_type | client_credentials | OAuth2 client_credentials authentication flow is used for machine to machine communication |
| scope | das-api/das-access | Scopes (=roles), if any, separated by spaces which are required to use the DAS API |
| client_assertion_type | urn:ietf:params:oauth:client-assertion-type:jwt-bearer | The client_assertion_type indicates to the authorization server the method used to authenticate, private_key_jwt requires jwt-bearer |
| client_assertion | eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkYXMtYXBpLWF1dG giLCJzdWIiOiJkYXMtYXBpLWF1dGgiLCJhdWQiOiJodHRwczovL2xvZ2luZG V2LndpcG8uaW50OjQ0My9hbS9vYXV0aDIvYWNjZXNzX3Rva2VuIiwiZXh wIjoxNjIyNDUwNzI4fQ.BLA6k2kKKFVm6AG-DPDpRU_5JDFGRF1dHjKul7saWCv5OxXGg4EY-J9e1p8Dg0ngD2dZ2grkJ2su7jaHy67YEw | The JWT generated in the paragraph above |
| 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 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 | Priority documents are stored for an undetermined period of time | |
| PCT priority documents originated from RO/IB | FORBIDDEN | Upon OSF requests, PCT RO/IB priority documents are retrieved from PCT DAS API and stored temporary in S3 until offices fetch the documents then documents are permanently deleted form the transit area (based on current usage average transit time is about 3 days) |
| National priority documents | Priority documents are stored for an undetermined period of time |
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
| 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
Exchange flow to replace document content for correction purpose
Exchange flow to retrieve document hosted in WIPO DAS
| 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
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
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 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
| If OSF does not delete the downloaded file, WIPO DAS will delete it after a pre-defined period (e.g. 1 week) |
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:
For advanced API Security, the FAPI (Financial grade API) – Part 2 standard adds an extra-layer on top of OAuth2.0 and OIDC.
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 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:
Protect access to API
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:
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.
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:
Files | Description |
|---|---|
| es256_cert.pem | Certificate file that will be communicated to WIPO for the configuration of the private_key_jwt client authentication |
| es256_private.pem | Must never be communicated and kept secret, used by the client to sign the private_key_jwt authentication request |
| es256_public.pem | Used only at the generation step, kept for record |
| openssl.cnf | Used only at the generation step, kept for record |
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:
Attribute | Example | Description |
|---|---|---|
| iss | das-api-auth | Issuer: Client id |
| sub | das-api-auth | Subject: Client id |
| aud | https://logindev.wipo.int:443/am/oauth2/access_token | Audience: Token endpoint of the authorization server |
| exp | 1622450728 | Expiration time: The expiration time of the data, current time + small amount of seconds (current epoch + 10s is ok) |
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:
POST parameter | example | Description |
|---|---|---|
| grant_type | client_credentials | OAuth2 client_credentials authentication flow is used for machine to machine communication |
| scope | das-api/das-access | Scopes (=roles), if any, separated by spaces which are required to use the DAS API |
| client_assertion_type | urn:ietf:params:oauth:client-assertion-type:jwt-bearer | The client_assertion_type indicates to the authorization server the method used to authenticate, private_key_jwt requires jwt-bearer |
| client_assertion | eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkYXMtYXBpLWF1dG giLCJzdWIiOiJkYXMtYXBpLWF1dGgiLCJhdWQiOiJodHRwczovL2xvZ2luZG V2LndpcG8uaW50OjQ0My9hbS9vYXV0aDIvYWNjZXNzX3Rva2VuIiwiZXh wIjoxNjIyNDUwNzI4fQ.BLA6k2kKKFVm6AG-DPDpRU_5JDFGRF1dHjKul7saWCv5OxXGg4EY-J9e1p8Dg0ngD2dZ2grkJ2su7jaHy67YEw | The JWT generated in the paragraph above |
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 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 | Priority documents are stored for an undetermined period of time | |
| PCT priority documents originated from RO/IB | FORBIDDEN | Upon OSF requests, PCT RO/IB priority documents are retrieved from PCT DAS API and stored temporary in S3 until offices fetch the documents then documents are permanently deleted form the transit area (based on current usage average transit time is about 3 days) |
| National priority documents | Priority documents are stored for an undetermined period of time |
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
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
Exchange flow to replace document content for correction purpose
Exchange flow to retrieve document hosted in WIPO DAS
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
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
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 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
| If OSF does not delete the downloaded file, WIPO DAS will delete it after a pre-defined period (e.g. 1 week) |