From 1d3eacf4bdc8da1076ffdc3ba2ed29b2588f213c Mon Sep 17 00:00:00 2001 From: pietfried Date: Tue, 19 Mar 2024 14:48:30 +0100 Subject: [PATCH] extended documentation Signed-off-by: pietfried --- README.md | 2 +- include/evse_security/evse_security.hpp | 28 ++++++++++++------------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 9673342..2106346 100644 --- a/README.md +++ b/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 diff --git a/include/evse_security/evse_security.hpp b/include/evse_security/evse_security.hpp index 64e1068..e7e6022 100644 --- a/include/evse_security/evse_security.hpp +++ b/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,7 +79,7 @@ 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 @@ -87,8 +87,8 @@ class EvseSecurity { 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();