Revize a6727aa9

Re #8472 - Added missing docstrings to KeyService and CertificateService classes

src/services/certificate_service.py

@@ -22 +22 @@
     # TODO usages present in method parameters but not in class diagram
     def create_root_ca(self, key: PrivateKey, subject: Subject, extensions: str = "", config: str = "",
                        usages=None):
+        """
+        Creates a root CA certificate based on the given parameters.
+        :param key: Private key to be used when generating the certificate
+        :param subject: Subject to be used put into the certificate
+        :param config: String containing the configuration to be used
+        :param extensions: Name of the section in the configuration representing extensions
+        :param usages: A dictionary containing usages of the certificate to be generated (see constants.py)
+        :return: An instance of Certificate class representing the generated root CA cert
+        """
         if usages is None:
             usages = {}
 
@@ -32 +41 @@
         usages[CA_ID] = True
 
         # wrap into Certificate class
-        certificate = self.__create_wrapper(cert_pem, key.private_key_id, subject.common_name, usages, 0,
+        certificate = self.__create_wrapper(cert_pem, key.private_key_id, usages, 0,
                                             ROOT_CA_ID)
 
         # store the wrapper into the repository
@@ -43 +52 @@
 
         return certificate
 
-    def __create_wrapper(self, cert_pem, private_key_id, common_name, usages, parent_id, cert_type):
+    def __create_wrapper(self, cert_pem, private_key_id, usages, parent_id, cert_type):
+        """
+        Wraps the given parameters using hte Certificate class. Uses CryptographyService to find out the notBefore and
+        notAfter fields.
+        :param cert_pem: PEM of the cert. to be wrapped
+        :param private_key_id: ID of the private key used to create the given certificate
+        :param usages: A dictionary containing usages of the generated certificate generated (see constants.py)
+        :param parent_id: ID of the CA that issued this certificate
+        :param cert_type: Type of this certificate (see constants.py)
+        :return: An instance of the Certificate class wrapping the values passed  via method parameters
+        """
         # parse the generated pem for subject and notBefore/notAfter fields
+        # TODO this could be improved in the future in such way that calling openssl is not required to parse the dates
         subj, not_before, not_after = self.cryptography_service.parse_cert_pem(cert_pem)
         # format the parsed date
         not_before_formatted = time.strftime(DATE_FORMAT, not_before)
         not_after_formatted = time.strftime(DATE_FORMAT, not_after)
 
         # create a certificate wrapper
-        certificate = Certificate(-1, common_name, not_before_formatted, not_after_formatted, cert_pem,
+        certificate = Certificate(-1, subj.common_name, not_before_formatted, not_after_formatted, cert_pem,
                                   private_key_id, cert_type, parent_id, usages)
 
         return certificate
@@ -59 +79 @@
     # TODO config parameter present in class diagram but not here (unused)
     def create_ca(self, subject_key: PrivateKey, subject: Subject, issuer_cert: Certificate, issuer_key: PrivateKey,
                   extensions: str = "", days: int = 30, usages=None):
+        """
+        Creates an intermediate CA certificate issued by the given parent CA.
+        :param subject_key: Private key to be used when generating the certificate
+        :param subject: Subject to be used put into the certificate
+        :param issuer_cert: Issuer certificate that will sign the CSR required to create an intermediate CA
+        :param issuer_key: PK used to generate the issuer certificate
+        :param extensions: Extensions to be used when generating the certificate
+        :param usages: A dictionary containing usages of the certificate to be generated (see constants.py)
+        :param days: Number of days for which the generated cert. will be considered valid
+        :return: An instance of Certificate class representing the generated intermediate CA cert
+        """
         if usages is None:
             usages = {}
 
@@ -74 +105 @@
         usages[CA_ID] = True
 
         # wrap into Certificate class
-        self.__create_wrapper(cert_pem, subject_key.private_key_id, subject.common_name, usages,
+        self.__create_wrapper(cert_pem, subject_key.private_key_id, usages,
                               issuer_cert.certificate_id, INTERMEDIATE_CA_ID)
 
         # parse the generated pem for subject and notBefore/notAfter fields
@@ -102 +133 @@
     def create_end_cert(self, subject_key: PrivateKey, subject: Subject, issuer_cert: Certificate,
                         issuer_key: PrivateKey,
                         extensions: str = "", days: int = 30, usages=None):
+        """
+        Creates an end certificate issued by the given parent CA.
+        :param subject_key: Private key to be used when generating the certificate
+        :param subject: Subject to be used put into the certificate
+        :param issuer_cert: Issuer certificate that will sign the CSR required to create an intermediate CA
+        :param issuer_key: PK used to generate the issuer certificate
+        :param extensions: Extensions to be used when generating the certificate
+        :param usages: A dictionary containing usages of the certificate to be generated (see constants.py)
+        :param days: Number of days for which the generated cert. will be considered valid
+        :return: An instance of Certificate class representing the generated cert
+        """
         if usages is None:
             usages = {}
 
@@ -113 +155 @@
                                                         days=days)
 
         # wrap the generated certificate using Certificate class
-        certificate = self.__create_wrapper(cert_pem, subject_key.private_key_id, subject.common_name, usages,
+        certificate = self.__create_wrapper(cert_pem, subject_key.private_key_id, usages,
                                             issuer_cert.certificate_id, CERTIFICATE_ID)
 
         created_id = self.certificate_repository.create(certificate)
@@ -123 +165 @@
         return certificate
 
     def get_certificate(self, unique_id: int) -> Certificate:
+        """
+        Tries to fetch a certificate from the certificate repository using a given id.
+        :param unique_id: ID of the certificate to be fetched
+        :return: Instance of the Certificate class containing a certificate with the given id or `None` if such
+        certificate is not found
+        """
         return self.certificate_repository.read(unique_id)
 
     def get_certificates(self, cert_type=None) -> List[Certificate]:
+        """
+        Tries to fetch a list of all certificates from the certificate repository. Using the `cert_type` parameter only
+        certificates of the given type can be returned.
+        :param cert_type: Type of certificates to be returned
+        :return: List of instances of the Certificate class representing all certificates present in the certificate
+        repository. An empty list is returned when no certificates are found.
+        """
         return self.certificate_repository.read_all(cert_type)
 
     def get_chain_of_trust(self, from_id: int, to_id: int = -1, exclude_root=True) -> List[Certificate]:
@@ -178 +233 @@
 
         return chain_of_trust
 
-    def delete_certificate(self, unique_id):
+    def delete_certificate(self, unique_id) -> bool:
         """
         Deletes a certificate
 
         :param unique_id: ID of specific certificate
 
-        :return: the result of whether the deletion was successful
+        :return: `True` when the deletion was successful. `False` in other case
         """
         # TODO delete children?
         return self.certificate_repository.delete(unique_id)