mms-client 1.6.0__tar.gz → 1.8.0__tar.gz

{mms_client-1.6.0 → mms_client-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mms-client
-Version: 1.6.0
+Version: 1.8.0
 Summary: API client for accessing the MMS
 Home-page: https://github.com/ElectroRoute-Japan/mms-client
 Author: Ryan Wood
@@ -22,7 +22,9 @@ Requires-Dist: backoff (>=2.2.1,<3.0.0)
 Requires-Dist: cryptography (>=42.0.5,<43.0.0)
 Requires-Dist: lxml (>=5.1.0,<6.0.0)
 Requires-Dist: pendulum (>=3.0.0,<4.0.0)
+Requires-Dist: pycryptodomex (>=3.20.0,<4.0.0)
 Requires-Dist: pydantic (>=2.6.3,<3.0.0)
+Requires-Dist: pydantic-extra-types (>=2.7.0,<3.0.0)
 Requires-Dist: pydantic-xml (>=2.9.0,<3.0.0)
 Requires-Dist: requests (>=2.31.0,<3.0.0)
 Requires-Dist: requests-pkcs12 (>=1.24,<2.0)
@@ -43,6 +45,9 @@ The underlying API sends and receives XML documents. Each of these request or re
 
 After the data has been converted and added to the outer request object, it is sent to the appropriate server endpoint via a Zeep client. The client certificate is also injected into the request using a PCKS12 adaptor.
 
+## Domain
+The domain to use when signing the content ID to MTOM attachments is specified when creating the client. This is not verified by the server, but it is used to generate the content ID for the MTOM attachments. As such, it is important to ensure that the domain is correct.
+
 # Serialization
 This library relies on Pydantic 2 and the pydantic-xml library for serialization/deserialization. As such, any type in this library can be converted to not only XML, but to JSON as well. This is extremely useful if you're trying to build a pass-through API service or something similar.
 
@@ -142,7 +147,7 @@ from mms_client.utils.web import ClientType
 cert = Certificate("/path/to/my/cert.p12", "fake_passphrase")
 
 # Create a new MMS client
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert)
 
 # Create our request offer
 request_offer = OfferData(
@@ -176,14 +181,14 @@ There's a lot of code here but it's not terribly difficult to understand. All th
 If you want to test your MMS connection, you can try using the test server:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
 ```
 
 ## Connecting as a Market Admin
 If you're connecting as a market operator (MO), you can connect in admin mode:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
 ```
 
 ## Auditing XML Requests & Responses
@@ -202,7 +207,7 @@ class TestAuditPlugin(AuditPlugin):
     def audit_response(self, mms_response: bytes) -> None:
         self.response = mms_response
 
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, plugins=[TestAuditPlugin()])
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, plugins=[TestAuditPlugin()])
 ```
 
 This same input allows for the user to create their own plugins and add them to the Zeep client, allowing for a certain amount of extensibility.
@@ -216,6 +221,10 @@ This client is not complete. Currently, it supports the following endpoints:
 - MarketQuery_AwardResultsQuery
 - RegistrationSubmit_Resource
 - RegistrationQuery_Resource
+- ReportCreateRequest
+- ReportListRequest
+- ReportDownloadRequestTrnID
+- BSP_ResourceList
 
 We can add support for additional endpoints as time goes on, and independent contribution is, of course, welcome. However, support for attachments is currently limited because none of the endpoints we support currently require them. We have implemented attachment support up to the client level, but we haven't developed an architecture for submitting them through an endpoint yet.
 

{mms_client-1.6.0 → mms_client-1.8.0}/README.md

@@ -11,6 +11,9 @@ The underlying API sends and receives XML documents. Each of these request or re
 
 After the data has been converted and added to the outer request object, it is sent to the appropriate server endpoint via a Zeep client. The client certificate is also injected into the request using a PCKS12 adaptor.
 
+## Domain
+The domain to use when signing the content ID to MTOM attachments is specified when creating the client. This is not verified by the server, but it is used to generate the content ID for the MTOM attachments. As such, it is important to ensure that the domain is correct.
+
 # Serialization
 This library relies on Pydantic 2 and the pydantic-xml library for serialization/deserialization. As such, any type in this library can be converted to not only XML, but to JSON as well. This is extremely useful if you're trying to build a pass-through API service or something similar.
 
@@ -110,7 +113,7 @@ from mms_client.utils.web import ClientType
 cert = Certificate("/path/to/my/cert.p12", "fake_passphrase")
 
 # Create a new MMS client
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert)
 
 # Create our request offer
 request_offer = OfferData(
@@ -144,14 +147,14 @@ There's a lot of code here but it's not terribly difficult to understand. All th
 If you want to test your MMS connection, you can try using the test server:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
 ```
 
 ## Connecting as a Market Admin
 If you're connecting as a market operator (MO), you can connect in admin mode:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
 ```
 
 ## Auditing XML Requests & Responses
@@ -170,7 +173,7 @@ class TestAuditPlugin(AuditPlugin):
     def audit_response(self, mms_response: bytes) -> None:
         self.response = mms_response
 
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, plugins=[TestAuditPlugin()])
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, plugins=[TestAuditPlugin()])
 ```
 
 This same input allows for the user to create their own plugins and add them to the Zeep client, allowing for a certain amount of extensibility.
@@ -184,6 +187,10 @@ This client is not complete. Currently, it supports the following endpoints:
 - MarketQuery_AwardResultsQuery
 - RegistrationSubmit_Resource
 - RegistrationQuery_Resource
+- ReportCreateRequest
+- ReportListRequest
+- ReportDownloadRequestTrnID
+- BSP_ResourceList
 
 We can add support for additional endpoints as time goes on, and independent contribution is, of course, welcome. However, support for attachments is currently limited because none of the endpoints we support currently require them. We have implemented attachment support up to the client level, but we haven't developed an architecture for submitting them through an endpoint yet.
 

{mms_client-1.6.0 → mms_client-1.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "mms_client"
-version = "v1.6.0"
+version = "v1.8.0"
 description = "API client for accessing the MMS"
 authors = ["Ryan Wood <ryan.wood@electroroute.co.jp>"]
 readme = "README.md"
@@ -32,6 +32,8 @@ cryptography = "^42.0.5"
 pydantic-xml = "^2.9.0"
 lxml = "^5.1.0"
 backoff = "^2.2.1"
+pycryptodomex = "^3.20.0"
+pydantic-extra-types = "^2.7.0"
 
 [tool.poetry.group.dev.dependencies]
 black = "^24.2.0"
@@ -48,7 +50,6 @@ pytest-mock = "^3.12.0"
 mock = "^5.1.0"
 lxml-stubs = "^0.5.1"
 pyfakefs = "^5.3.5"
-pydantic-extra-types = "^2.6.0"
 responses = "^0.25.0"
 types-urllib3 = "^1.26.25.14"
 

mms_client-1.8.0/src/mms_client/security/certs.py

@@ -0,0 +1,77 @@
+"""Contains functionality associated with certificates."""
+
+from pathlib import Path
+from ssl import PROTOCOL_TLSv1_2
+from typing import Union
+
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
+from cryptography.hazmat.primitives.serialization import Encoding
+from cryptography.hazmat.primitives.serialization import NoEncryption
+from cryptography.hazmat.primitives.serialization import PrivateFormat
+from cryptography.hazmat.primitives.serialization import PublicFormat
+from cryptography.hazmat.primitives.serialization.pkcs12 import load_key_and_certificates
+from requests_pkcs12 import Pkcs12Adapter
+
+
+class Certificate:
+    """Describes a certificate composed of a cert file and a key file."""
+
+    # The encoding to use for MMS certificates
+    encoding = Encoding.PEM
+
+    def __init__(self, cert: Union[str, Path, bytes], passphrase: str):
+        """Create a new Certificate.
+
+        Creates a new certificate from the absolute path to the certificate file and a passpharse.
+
+        Arguments:
+        cert:           The certificate file. If a string, it should be the absolute path to the certificate file. If
+                        bytes, it should be the contents of the certificate file.
+        passphrase:     The passphrase the certificate is encrypted with
+        """
+        # Get the certificate file contents
+        if isinstance(cert, (str, Path)):
+            with open(cert, "rb") as file:
+                self._cert = file.read()
+        else:
+            self._cert = cert
+
+        # Save the passphrase
+        self._passphrase = passphrase
+
+        # Load the private key using the cryptography library
+        private_key, _, _ = load_key_and_certificates(self._cert, self._passphrase.encode("UTF-8"))
+        if isinstance(private_key, RSAPrivateKey):
+            self._private = private_key
+        else:
+            raise TypeError(f"Private key of type ({type(private_key).__name__}) was not expected.")
+
+    @property
+    def certificate(self) -> bytes:
+        """Return the certificate data."""
+        return self._cert
+
+    @property
+    def passphrase(self) -> str:
+        """Return the full path to the passphrase."""
+        return self._passphrase
+
+    def public_key(self) -> bytes:
+        """Extract the public key from the certificate.
+
+        Returns: The public key in PEM format.
+        """
+        return self._private.public_key().public_bytes(Certificate.encoding, PublicFormat.PKCS1)
+
+    def private_key(self) -> bytes:
+        """Extract the private key from the certificate.
+
+        THIS SHOULD NOT, UNDER ANY CIRCUMSTANCES, BE PRINTED OR LOGGED!!!
+
+        Returns: The private key in PEM format.
+        """
+        return self._private.private_bytes(Certificate.encoding, PrivateFormat.PKCS8, NoEncryption())
+
+    def to_adapter(self) -> Pkcs12Adapter:
+        """Convert the certificate to a Pkcs12Adapter."""
+        return Pkcs12Adapter(pkcs12_data=self._cert, pkcs12_password=self._passphrase, ssl_protocol=PROTOCOL_TLSv1_2)

mms_client-1.8.0/src/mms_client/security/crypto.py

@@ -0,0 +1,65 @@
+"""Contains objects for cryptographic operations."""
+
+from base64 import b64decode
+from base64 import b64encode
+
+from Cryptodome.Hash import SHA256
+from Cryptodome.PublicKey import RSA
+from Cryptodome.Signature import pkcs1_15
+
+from mms_client.security.certs import Certificate
+
+
+class CryptoWrapper:
+    """Wraps the cryptographic operations necessary for signing and encrypting MMS payload data."""
+
+    def __init__(self, cert: Certificate):
+        """Create a new CryptoWrapper with the given certificate.
+
+        Arguments:
+        cert (Certificate): The certificate to use for cryptographic operations.
+        """
+        # Extract the public key and private key data from the certificate
+        private_key = RSA.import_key(cert.private_key())
+        public_key = RSA.import_key(cert.public_key())
+
+        # Create a new signer from the private key and a new verifier from the public key
+        self._signer = pkcs1_15.new(private_key)
+        self._verifier = pkcs1_15.new(public_key)
+
+    def verify(self, content: bytes, signature: bytes) -> bool:
+        """Verify a signature against the given content using the certificate.
+
+        Arguments:
+        content (bytes):    The content to verify.
+        signature (bytes):  The signature to verify against the content.
+
+        Returns:    True if the signature is valid, False otherwise.
+        """
+        # Hash the content using SHA256
+        hashed = SHA256.new(content)
+
+        # Verify the signature using the public key. This will raise a ValueError if the signature is invalid.
+        # We catch this exception and return False to indicate that the signature is invalid.
+        try:
+            self._verifier.verify(hashed, b64decode(signature))
+            return True
+        except ValueError:
+            return False
+
+    def sign(self, data: bytes) -> bytes:
+        """Create a signature from the given data using the certificate.
+
+        Arguments:
+        data (bytes):   The data to be encrypted.
+
+        Returns:    A base64-encoded string containing the signature.
+        """
+        # First, hash the data using SHA256
+        hashed = SHA256.new(data)
+
+        # Next, sign the hash using the private key
+        signature = self._signer.sign(hashed)
+
+        # Finally, return the base64-encoded signature
+        return b64encode(signature)