magpie.api.management.network.network_utils
===========================================

.. py:module:: magpie.api.management.network.network_utils


Attributes
----------

.. autoapisummary::

   magpie.api.management.network.network_utils.LOGGER


Functions
---------

.. autoapisummary::

   magpie.api.management.network.network_utils.pem_files
   magpie.api.management.network.network_utils._pem_file_content
   magpie.api.management.network.network_utils._pem_file_passwords
   magpie.api.management.network.network_utils.create_private_key
   magpie.api.management.network.network_utils.jwks
   magpie.api.management.network.network_utils._private_keys
   magpie.api.management.network.network_utils.encode_jwt
   magpie.api.management.network.network_utils.decode_jwt
   magpie.api.management.network.network_utils.get_network_models_from_request_token


Module Contents
---------------

.. py:data:: LOGGER

.. py:function:: pem_files(settings_container: Optional[magpie.typedefs.AnySettingsContainer] = None) -> List[magpie.typedefs.Str]

.. py:function:: _pem_file_content(primary: bool = False, settings_container: Optional[magpie.typedefs.AnySettingsContainer] = None) -> List[bytes]

   Return the content of all PEM files


.. py:function:: _pem_file_passwords(primary: bool = False, settings_container: Optional[magpie.typedefs.AnySettingsContainer] = None) -> List[Optional[bytes]]

   Return the passwords used to encrypt the PEM files.
   The passwords will be returned in the same order as the file content from `_pem_file_content`.

   If a file is not encrypted with a password, a ``None`` value will be returned in place of the password.

   For example: if there are 4 PEM files and the second and fourth are not encrypted, this will return
   ``["password1", None, "password2"]``


.. py:function:: create_private_key(filename: magpie.typedefs.Str, password: Optional[bytes] = None, settings_container: Optional[magpie.typedefs.AnySettingsContainer] = None) -> None

   Create a private key file at the specified filename. Encrypt it using the password if specified.
   If password is None and the filename matches a file in MAGPIE_NETWORK_PEM_FILES, the associated
   password specified in MAGPIE_NETWORK_PEM_PASSWORDS will be used instead.

   .. warning::
       This function should only be used to create a file if MAGPIE_NETWORK_CREATE_MISSING_PEM_FILE is
       truthy. This is not enforced in this function.


.. py:function:: jwks(primary: bool = False, settings_container: Optional[magpie.typedefs.AnySettingsContainer] = None) -> jwcrypto.jwk.JWKSet

   Return a JSON Web Key Set containing all JSON Web Keys loaded from the PEM files listed
   in ``MAGPIE_NETWORK_PEM_FILES``.


.. py:function:: _private_keys(primary: bool = False) -> Dict[magpie.typedefs.Str, cryptography.hazmat.primitives.asymmetric.types.PrivateKeyTypes]

   Return a dictionary containing key ids and private keys from the PEM files listed in ``MAGPIE_NETWORK_PEM_FILES``.

   If the ``primary`` argument is True, only the primary key will be included in the returned list.


.. py:function:: encode_jwt(claims: magpie.typedefs.JSON, audience_name: magpie.typedefs.Str, settings_container: Optional[magpie.typedefs.AnySettingsContainer] = None) -> magpie.typedefs.Str

   Encode claims as a JSON web token.

   Unless overridden by a field in the ``claims`` argument, the ``"iss"`` claim will default to
   `MAGPIE_NETWORK_INSTANCE_NAME`, the ``"exp"`` claim will default to `MAGPIE_NETWORK_INTERNAL_TOKEN_EXPIRY`,
   and the ``"aud"`` claim will default to ``audience_name``. The JWT will be signed with `Magpie`'s primary private
   key (see the `_private_keys` function for details) using the asymmetric RS256 algorithm.


.. py:function:: decode_jwt(token: magpie.typedefs.Str, node: magpie.models.NetworkNode, settings_container: Optional[magpie.typedefs.AnySettingsContainer] = None) -> magpie.typedefs.JSON

   Decode a JSON Web Token issued by a node in the network.

   The token must include the ``"exp"``, ``"aud"``,  and ``"iss"`` claims.
   If the issuer is not the same as ``node.name``, or the audience is not this instance (i.e. the same as
   ``MAGPIE_NETWORK_INSTANCE_NAME``), or the token is expired, an error will be raised.
   An error will also be raised if the token cannot be verified with the issuer node's public key.


.. py:function:: get_network_models_from_request_token(request: pyramid.request.Request, create_network_remote_user: bool = False) -> Tuple[magpie.models.NetworkNode, Optional[magpie.models.NetworkRemoteUser]]

   Return a ``NetworkNode`` and associated ``NetworkRemoteUser`` determined by parsing the claims in the JWT included
   in the ``request`` argument.

   If the ``NetworkRemoteUser`` does not exist and ``create_network_remote_user`` is ``True``, this creates a new
   ``NetworkRemoteUser`` associated with the anonymous user for the given ``NetworkNode`` and adds it to the current
   database transaction.