openg2p-security.md

openg2p-security

Introduction

Source code: https://github.com/openg2p/openg2p-security

This repository contains Odoo modules that help PBMS/Registry to perform cryptography operations like encrypt, decrypt, sign, verify, etc. and interface with external encryption modules like Keymanager. This also enables the registry to encrypt and store data or to decrypt the data on demand.

Modules

This repository contains the following modules:

G2P Encryption: Base

Module Name: g2p_encryption

• This module contains the base model for g2p.encryption.provider .
• This base model exposes some basic cryptographic operations as Python functions so that subclasses can implement the functions. The type field drives which type of encryption provider to use.
  • This means custom encryption providers are supposed to extend this model, add their type, and implement the above crypto operations according to their type. Details are given below.
• The cryptographic operations that are supported currently (that custom encryption providers can implement) are:
  • encrypt: encrypt given bytes.
  • decrypt: decrypt given bytes.
  • jwt_sign: Signs a given string/dictionary and returns a JWT.
  • jwt_verify: Verifies if the given JWT is valid.
  • get_jwks: get public keys/certificates of the encryption provider, which external parties should use to verify signatures, etc.
• This module also creates a default encryption provider instance (which can also be modified by the custom encryption providers), which will be used in all places if no purpose-specific encryption providers are created. This also enables users to just install the modules and use them directly without configuring anything.

G2P Encryption: Keymanager

Module Name: g2p_encryption_keymanager

Installation Prerequisites: Keymanager and Keycloak.

• ​This module adds a new type called keymanager to the g2p.encryption.provider model.
• The module implements all the following functions by interacting with Keymanager APIs:
  • encrypt: runs /v1/keymanager/encrypt API call to encrypt given bytes.
  • decrypt: runs /v1/keymanager/decrypt API call to decrypt given bytes.
  • jwt_sign: runs /v1/keymanager/jwtSign API call to return signet JWT.
  • jwt_verify: runs /v1/keymanager/jwtVerify API call to verify given JWT.
  • get_jwks: gets certificates using /v1/keymanager/getAllCertificates and converts them to JWKs.

G2P Encryption: Rest API

Module Name: g2p_encryption_rest_api

• Exposes a /.well-known/jwks.json rest API. When called, this API will combine and return the JWKs returned by get_jwks function of all the encryption providers.

G2P Registry Encryption

Module Name: g2p_registry_encryption

• This module uses an encryption provider (the type of provider doesn't matter, because it is abstracted out) to encrypt and decrypt Registry fields on demand. Registry fields that should be encrypted can be configured on the encryption provider.
• This also adds the ability to turn registry encryption on or off in settings. This operation is only allowed for users with the Crypto Admin role.
• This also adds an ability where Crypto Admin users can decrypt the registry on demand to view the encrypted records.
• Whenever a new registry entry is added/updated, the to-be encrypted field data is collected into a JSON string, encrypted, and stored in one field. And vice-versa for decryption.

Creating a custom Encryption Provider

• Inherit g2p.encryption.provider model. Add a new type to the type Selection field using selection_add. Example

  type = fields.Selection(selection_add=[("mock", "Mock")])

• Implement the following functions:

  • encrypt_data_{type}
  • decrypt_data_{type}
  • jwt_sign_{type}
  • jwt_verify_{type}
  • get_jwks_{type}

• Example:

  def encrypt_data_mock(self, data: bytes, **kwargs) -> bytes:
      ...
  def decrypt_data_mock(self, data: bytes, **kwargs) -> bytes:
      ...
  def jwt_sign_mock(self, data, include_payload=True, include_certificate=True, include_cert_hash=True) -> str:
      ...
  def jwt_verify_mock(self, data: str, **kwargs):
      ...
  def get_jwks_mock(self, **kwargs):
      ...

Configuration

• Encryption Providers' configs can be found under Settings Menu -> Encryption Providers Page. Configuration properties will vary depending on the encryption provider.
• If the encryption provider type is Keymanager, then the following config can be configured on the same Encryption Providers page:
  • If ENV Variable value is not empty against the config parameter below, it can be configured using the ENV var also.

Name	Property name	ENV Variable	Description
Keymanager API Base URL	keymanager_api_base_url	KEYMANAGER_API_BASE_URL	Base URL to access Keymanager APIs. Defaults to k8s cluster local Keymanager URL, http://keymanagar.keymanager/v1/keymanager.
Keymanager Auth URL	keymanager_auth_url	KEYMANAGER_AUTH_URL	Auth URL to get auth for Keymanager APIs. Defaults to k8s local Keycloak token URL, http://keycloak.keycloak/realms/openg2p/protocol/openid-connect/token.
Keymanager Auth Client ID	keymanager_auth_client_id	KEYMANAGER_AUTH_CLIENT_ID	Keymanager Keycloak client ID. Defaults to openg2p-admin-client.
Keymanager Auth Client Secret	keymanager_auth_client_secret	KEYMANAGER_AUTH_CLIENT_SECRET	Keymanager Keycloak client secret.
Keymanager Auth Grant Type	keymanager_auth_grant_type	KEYMANAGER_AUTH_GRANT_TYPE	Defaults to client_secret.
Keymanager Encrypt Application ID	keymanager_encrypt_application_id		Defaults to REGISTRATION.
Keymanager Encrypt Reference ID	keymanager_encrypt_reference_id		Defaults to ENCRYPT.
Keymanager Sign Application ID	keymanager_sign_application_id		Defaults to ID_REPO.
Keymanager Sign Reference ID	keymanager_sign_reference_id

• For Registry Encryption, the following config can be configured on the Encryption Providers page:

Name	Property name	Description
Registry Fields to Encrypt	registry_fields_to_enc	Registry fields that are supposed to be considered for encryption-decryption. This should be given as a list. Defaults: ["name","family_name","given_name","addl_name","display_name","address","birth_place"]
Registry Encrypted Field Placeholder	registry_enc_field_placeholder	String placeholder for an encrypted field in registry. Defaults to encrypted.