extended documentation

Signed-off-by: pietfried <[email protected]>

README.md

@@ -45,7 +45,7 @@ We allow any certificate structure with the following recommendations:
 
 **Important:** when requesting leaf certificates with [get_key_pair](https://github.com/EVerest/libevse-security/blob/5cd5f8284229ffd28ae1dfed2137ef194c39e732/lib/evse_security/evse_security.cpp#L820) care should be taken if you require the full certificate chain.
 
-If a full chain is **Leaf->SubCA2->SubCA1->Root**, it is recommended to have the root certificate in a single file, **CSMS_ROOT_CA.pem** for example. The remaining **Leaf->SubCA2->SubCA1** should be placed in a file **CPO_CERT_CHAIN.pem**. 
+If a full chain is **Leaf->SubCA2->SubCA1->Root**, it is recommended to have the root certificate in a single file, **V2G_ROOT_CA.pem** for example. The **Leaf->SubCA2->SubCA1** should be placed in a file e.g. **SECC_CERT_CHAIN.pem**. 
 
 ## Certificate Signing Request
 

include/evse_security/evse_security.hpp

@@ -24,10 +24,10 @@ struct LinkPaths {
 };
 
 struct DirectoryPaths {
-    fs::path csms_leaf_cert_directory;
-    fs::path csms_leaf_key_directory;
-    fs::path secc_leaf_cert_directory;
-    fs::path secc_leaf_key_directory;
+    fs::path csms_leaf_cert_directory; /**< csms leaf certificate for OCPP shall be located in this directory */
+    fs::path csms_leaf_key_directory;  /**< csms leaf key shall be located in this directory */
+    fs::path secc_leaf_cert_directory; /**< secc leaf certificate for ISO15118 shall be located in this directory */
+    fs::path secc_leaf_key_directory;  /**< secc leaf key shall be located in this directory */
 };
 struct FilePaths {
     // bundle paths
@@ -58,8 +58,8 @@ class EvseSecurity {
 
 public:
     /// @brief Constructor initializes the certificate and key storage using the given \p file_paths for the different
-    /// PKIs. For CA certificates CA either bundle files or directories containing the certificates must be specified.
-    /// For the SECC and CSMS leaf certificates, directories are specified.
+    /// PKIs. For CA certificates CA either bundle files or directories containing the certificates can be specified.
+    /// For the SECC and CSMS leaf certificates, directories must be specified.
     /// @param file_paths specifies the certificate and key storage locations on the filesystem
     /// @param private_key_password optional password for encrypted private keys
     /// @param max_fs_usage_bytes optional maximum filesystem usage for certificates. Defaults to
@@ -79,16 +79,16 @@ class EvseSecurity {
     /// @brief Destructor
     ~EvseSecurity();
 
-    /// @brief Installs the given \p certificate within the specified CA bundle file or directory is directories are
+    /// @brief Installs the given \p certificate within the specified CA bundle file or directory if directories are
     /// used. If the certificate already exists it will only be updated
     /// @param certificate PEM formatted CA certificate
     /// @param certificate_type specifies the CA certificate type
     /// @return result of the operation
     InstallCertificateResult install_ca_certificate(const std::string& certificate, CaCertificateType certificate_type);
 
     /// @brief Deletes the certificate specified by \p certificate_hash_data . If a CA certificate is specified, the
-    /// certificate is removed from the bundle. If a leaf certificate is specified, the file will be removed from the
-    /// filesystem. It will also delete all certificates issued by this certificate, so that we don't have invalid
+    /// certificate is removed from the bundle or directory. If a leaf certificate is specified, the file will be
+    /// removed from the filesystem. It will also delete all certificates issued by this certificate, so that no invalid
     /// hierarchies persisted on the filesystem
     /// @param certificate_hash_data specifies the certificate to be deleted
     /// @return result of the operation
@@ -107,7 +107,7 @@ class EvseSecurity {
     /// filesystem, this function checks if a private key is present for the given certificate on the filesystem. Two
     /// files are installed, one containing the single leaf (presuming it is the first in the chain) and also the full
     /// certificate chain. The \ref get_key_pair function will return a path to both files if they exist, the one
-    /// containing the single leaf, and the file containing the leaf plus SUBCAs
+    /// containing the single leaf, and the file containing the leaf including the SUBCAs if present
     /// @param certificate_chain PEM formatted certificate or certificate chain
     /// @param certificate_type type of the leaf certificate
     /// @return result of the operation
@@ -177,9 +177,9 @@ class EvseSecurity {
 
     /// @brief Searches the filesystem on the specified directories for the given \p certificate_type and retrieves the
     /// most recent certificate that is already valid and the respective key.  If no certificate is present or no key is
-    /// matching the certificate, this function returns std::nullopt. The function \ref update_leaf_certificate will
-    /// install two files for each leaf, one containing the single leaf and one containing the leaf plus any possible
-    /// SUBCAs
+    /// matching the certificate, this function returns a GetKeyPairStatus other than "Accepted". The function \ref
+    /// update_leaf_certificate will install two files for each leaf, one containing the single leaf and one containing
+    /// the leaf including any possible SUBCAs
     /// @param certificate_type type of the leaf certificate
     /// @param encoding specifies PEM or DER format
     /// @return contains response result
@@ -202,7 +202,7 @@ class EvseSecurity {
     int get_leaf_expiry_days_count(LeafCertificateType certificate_type);
 
     /// @brief Collects and deletes unfulfilled CSR private keys. It also deletes the expired
-    /// certificates, make sure the system clock is properly set for detecting expired certificates. A
+    /// certificates and makes sure the system clock is properly set for detecting expired certificates. A
     /// minimum of 'DEFAULT_MINIMUM_CERTIFICATE_ENTRIES' certificates to have a safeguard against
     /// a poorly set system clock
     void garbage_collect();