Merge pull request #223 from HaToHo/master

Added comments.

Author: Roland Hedberg

src/saml2/__init__.py

@@ -603,6 +603,11 @@ def get_xml_string_with_self_contained_assertion_within_advice_encrypted_asserti
         return ElementTree.tostring(tree, encoding="UTF-8")
 
     def get_xml_string_with_self_contained_assertion_within_encrypted_assertion(self, assertion_tag):
+        """ Makes a encrypted assertion only containing self contained namespaces.
+
+        :param assertion_tag: Tag for the assertion to be transformed.
+        :return: A new samlp.Resonse in string representation.
+        """
         prefix_map = self.get_prefix_map([self.encrypted_assertion._to_element_tree().find(assertion_tag)])
 
         tree = self._to_element_tree()

src/saml2/entity.py

@@ -504,14 +504,26 @@ def _add_info(self, msg, **kwargs):
                 msg.extension_elements = extensions
 
     def has_encrypt_cert_in_metadata(self, sp_entity_id):
+        """ Verifies if the metadata contains encryption certificates.
+
+        :param sp_entity_id: Entity ID for the calling service provider.
+        :return: True if encrypt cert exists in metadata, otherwise False.
+        """
         if sp_entity_id is not None:
             _certs = self.metadata.certs(sp_entity_id, "any", "encryption")
             if len(_certs) > 0:
                 return True
         return False
 
-
     def _encrypt_assertion(self, encrypt_cert, sp_entity_id, response, node_xpath=None):
+        """ Encryption of assertions.
+
+        :param encrypt_cert: Certificate to be used for encryption.
+        :param sp_entity_id: Entity ID for the calling service provider.
+        :param response: A samlp.Response
+        :param node_xpath: Unquie path to the element to be encrypted.
+        :return: A new samlp.Resonse with the designated assertion encrypted.
+        """
         _certs = []
         cbxs = CryptoBackendXmlSec1(self.config.xmlsec_binary)
         if encrypt_cert:
@@ -558,6 +570,15 @@ def _response(self, in_response_to, consumer_url=None, status=None,
         :param issuer: The issuer of the response
         :param sign: Whether the response should be signed or not
         :param to_sign: If there are other parts to sign
+        :param sp_entity_id: Entity ID for the calling service provider.
+        :param encrypt_assertion: True if assertions should be encrypted.
+        :param encrypt_assertion_self_contained: True if all encrypted assertions should have alla namespaces
+        selfcontained.
+        :param encrypted_advice_attributes: True if assertions in the advice element should be encrypted.
+        :param encrypt_cert_advice: Certificate to be used for encryption of assertions in the advice element.
+        :param encrypt_cert_assertion: Certificate to be used for encryption of assertions.
+        :param sign_assertion: True if assertions should be signed.
+        :param pefim: True if a response according to the PEFIM profile should be created.
         :param kwargs: Extra key word arguments
         :return: A Response instance
         """

src/saml2/response.py

@@ -799,6 +799,14 @@ def _assertion(self, assertion, verified=False):
             raise
 
     def decrypt_assertions(self, encrypted_assertions, decr_txt, issuer=None, verified=False):
+        """ Moves the decrypted assertion from the encrypted assertion to a list.
+
+        :param encrypted_assertions: A list of encrypted assertions.
+        :param decr_txt: The string representation containing the decrypted data. Used when verifying signatures.
+        :param issuer: The issuer of the response.
+        :param verified: If True do not verify signatures, otherwise verify the signature if it exists.
+        :return: A list of decrypted assertions.
+        """
         res = []
         for encrypted_assertion in encrypted_assertions:
             if encrypted_assertion.extension_elements:
@@ -815,11 +823,21 @@ def decrypt_assertions(self, encrypted_assertions, decr_txt, issuer=None, verifi
         return res
 
     def find_encrypt_data_assertion(self, enc_assertions):
+        """ Verifies if a list of encrypted assertions contains encrypted data.
+
+        :param enc_assertions: A list of encrypted assertions.
+        :return: True encrypted data exists otherwise false.
+        """
         for _assertion in enc_assertions:
                 if _assertion.encrypted_data is not None:
                     return True
 
     def find_encrypt_data_assertion_list(self, _assertions):
+        """ Verifies if a list of assertions contains encrypted data in the advice element.
+
+        :param _assertions: A list of assertions.
+        :return: True encrypted data exists otherwise false.
+        """
         for _assertion in _assertions:
             if _assertion.advice:
                 if _assertion.advice.encrypted_assertion:
@@ -828,6 +846,11 @@ def find_encrypt_data_assertion_list(self, _assertions):
                         return True
 
     def find_encrypt_data(self, resp):
+        """ Verifies if a saml response contains encrypted assertions with encrypted data.
+
+        :param resp: A saml response.
+        :return: True encrypted data exists otherwise false.
+        """
         _has_encrypt_data = False
         if resp.encrypted_assertion:
             res = self.find_encrypt_data_assertion(resp.encrypted_assertion)
@@ -843,6 +866,11 @@ def find_encrypt_data(self, resp):
         return False
 
     def parse_assertion(self, keys=None):
+        """ Parse the assertions for a saml response.
+
+        :param keys: A string representing a RSA key or a list of strings containing RSA keys.
+        :return: True if the assertions are parsed otherwise False.
+        """
         if self.context == "AuthnQuery":
             # can contain one or more assertions
             pass

src/saml2/server.py

@@ -337,10 +337,20 @@ def _authn_response(self, in_response_to, consumer_url,
         :param authn: A dictionary containing information about the
             authn context.
         :param issuer: The issuer of the response
+        :param policy:
         :param sign_assertion: Whether the assertion should be signed or not
         :param sign_response: Whether the response should be signed or not
         :param best_effort: Even if not the SPs demands can be met send a
             response.
+        :param encrypt_assertion: True if assertions should be encrypted.
+        :param encrypt_assertion_self_contained: True if all encrypted assertions should have alla namespaces
+        selfcontained.
+        :param encrypted_advice_attributes: True if assertions in the advice element should be encrypted.
+        :param encrypt_cert_advice: Certificate to be used for encryption of assertions in the advice element.
+        :param encrypt_cert_assertion: Certificate to be used for encryption of assertions.
+        :param authn_statement: Authentication statement.
+        :param sign_assertion: True if assertions should be signed.
+        :param pefim: True if a response according to the PEFIM profile should be created.
         :return: A response instance
         """
 
@@ -495,11 +505,20 @@ def create_authn_response(self, identity, in_response_to, destination,
         :param sp_entity_id: The entity identifier of the Service Provider
         :param name_id_policy: How the NameID should be constructed
         :param userid: The subject identifier
+        :param name_id: The identifier of the subject.
         :param authn: Dictionary with information about the authentication
             context
         :param issuer: Issuer of the response
         :param sign_assertion: Whether the assertion should be signed or not.
         :param sign_response: Whether the response should be signed or not.
+        :param encrypt_assertion: True if assertions should be encrypted.
+        :param encrypt_assertion_self_contained: True if all encrypted assertions should have alla namespaces
+        selfcontained.
+        :param encrypted_advice_attributes: True if assertions in the advice element should be encrypted.
+        :param encrypt_cert_advice: Certificate to be used for encryption of assertions in the advice element.
+        :param encrypt_cert_assertion: Certificate to be used for encryption of assertions.
+        :param sign_assertion: True if assertions should be signed.
+        :param pefim: True if a response according to the PEFIM profile should be created.
         :return: A response instance
         """