docs(CertificateManager/ICertificateManager): clarify API

lib/private/Security/CertificateManager.php

@@ -16,7 +16,15 @@
 use Psr\Log\LoggerInterface;
 
 /**
- * Manage trusted certificates for users
+ * Manage trusted certificates and the effective CA bundle used by Nextcloud.
+ *
+ * Uploaded PEM certificates are merged with the shipped default CA bundle to
+ * produce the effective bundle consumed by HTTP clients and external storage
+ * integrations.
+ *
+ * The uploaded certificates and generated bundle are stored under the
+ * files_external path for historical reasons, maintaining compatibility
+ * with pre-existing deployments.
  */
 class CertificateManager implements ICertificateManager {
 	private ?string $bundlePath = null;
@@ -30,7 +38,7 @@ public function __construct(
 	}
 
 	/**
-	 * Returns all certificates trusted by the user
+	 * Return the certificates stored in the internal upload area.
 	 *
 	 * @return ICertificate[]
 	 */
@@ -67,6 +75,9 @@ public function listCertificates(): array {
 		return $result;
 	}
 
+	/**
+	 * Check whether any uploaded certificates are present.
+	 */
 	private function hasCertificates(): bool {
 		if (!$this->config->getSystemValueBool('installed', false)) {
 			return false;
@@ -91,9 +102,14 @@ private function hasCertificates(): bool {
 	}
 
 	/**
-	 * create the certificate bundle of all trusted certificated
+	 * Rebuild the generated effected certificate bundle from:
+	 * - uploaded certificates
+	 * - the shipped default CA bundle
+	 * - the current system CA bundle, if present and different from the target
+	 *
+	 * The bundle is written atomically to /files_external/rootcerts.crt.
 	 */
-	public function createCertificateBundle(): void {
+	private function createCertificateBundle(): void {
 		$path = $this->getPathToCertificates();
 		$certs = $this->listCertificates();
 
@@ -143,11 +159,12 @@ public function createCertificateBundle(): void {
 	}
 
 	/**
-	 * Save the certificate and re-generate the certificate bundle
+	 * Store a certificate and regenerate the effective bundle.
 	 *
-	 * @param string $certificate the certificate data
-	 * @param string $name the filename for the certificate
-	 * @throws \Exception If the certificate could not get added
+	 * @param string $certificate Certificate data in PEM format
+	 * @param string $name File name to store the certificate under
+	 * @return ICertificate
+	 * @throws \Exception If the certificate cannot be stored or the bundle cannot be rebuilt
 	 */
 	#[\Override]
 	public function addCertificate(string $certificate, string $name): ICertificate {
@@ -172,7 +189,10 @@ public function addCertificate(string $certificate, string $name): ICertificate
 	}
 
 	/**
-	 * Remove the certificate and re-generate the certificate bundle
+	 * Remove a stored certificate and regenerate the effective bundle.
+	 *
+	 * @param string $name File name of the certificate to remove
+	 * @return bool False if the path is invalid, true otherwise
 	 */
 	#[\Override]
 	public function removeCertificate(string $name): bool {
@@ -193,16 +213,23 @@ public function removeCertificate(string $name): bool {
 	}
 
 	/**
-	 * Get the path to the certificate bundle
+	 * Get the relative path to the generated certificate bundle.
 	 */
 	#[\Override]
 	public function getCertificateBundle(): string {
 		return $this->getPathToCertificates() . 'rootcerts.crt';
 	}
 
 	/**
-	 * Get the full local path to the certificate bundle
-	 * @throws \Exception when getting bundle path fails
+	 * Get the local filesystem path to the effective certificate bundle.
+	 *
+	 * Returns the generated bundle when uploaded certificates exist, otherwise
+	 * falls back to the shipped default CA bundle.
+	 *
+	 * If resolving the generated bundle fails, the default bundle is returned as
+	 * a safe fallback.
+	 *
+	 * @throws \Exception If unable to retrieve/confirm the bundle path for any reason.
 	 */
 	#[\Override]
 	public function getAbsoluteBundlePath(): string {
@@ -230,12 +257,19 @@ public function getAbsoluteBundlePath(): string {
 		}
 	}
 
+	/**
+	 * Get the base path used to store uploaded certificates and the generated bundle.
+	 *
+	 * Kept under the files_external namespace for compatibility with existing
+	 * deployments.
+	 */
 	private function getPathToCertificates(): string {
 		return '/files_external/';
 	}
 
 	/**
-	 * Check if we need to re-bundle the certificates because one of the sources has updated
+	 * Determine whether the generated bundle must be rebuilt because the source
+	 * CA bundle has changed or the target bundle is missing.
 	 */
 	private function needsRebundling(): bool {
 		$targetBundle = $this->getCertificateBundle();
@@ -248,12 +282,15 @@ private function needsRebundling(): bool {
 	}
 
 	/**
-	 * get mtime of ca-bundle shipped by Nextcloud
+	 * Return the modification time of the shipped default CA bundle.
 	 */
 	protected function getFilemtimeOfCaBundle(): int {
 		return filemtime($this->getDefaultCertificatesBundlePath());
 	}
 
+	/**
+	 * Return the configured path to the shipped default CA bundle.
+	 */
 	#[\Override]
 	public function getDefaultCertificatesBundlePath(): string {
 		return $this->config->getSystemValueString('default_certificates_bundle_path', \OC::$SERVERROOT . '/resources/config/ca-bundle.crt');

lib/public/ICertificateManager.php

@@ -9,52 +9,67 @@
 namespace OCP;
 
 /**
- * Manage trusted certificates
+ * Manage trusted certificates and the effective CA bundle used by Nextcloud.
+ *
+ * Implementations provide access to uploaded trusted certificates and the
+ * generated bundle that is consumed by HTTP clients and external storage
+ * integrations.
+ *
  * @since 8.0.0
  */
 interface ICertificateManager {
 	/**
-	 * Returns all certificates trusted by the system
+	 * Returns all uploaded trusted certificates.
+	 *
+	 * This does not include the shipped default CA bundle or any system CA bundle
+	 * appended when building the effective bundle.
 	 *
 	 * @return \OCP\ICertificate[]
 	 * @since 8.0.0
 	 */
 	public function listCertificates(): array;
 
 	/**
-	 * @param string $certificate the certificate data
-	 * @param string $name the filename for the certificate
+	 * Add a trusted certificate to the certificate store.
+	 *
+	 * @param string $certificate The certificate data in PEM format
+	 * @param string $name The filename for the certificate
 	 * @return \OCP\ICertificate
-	 * @throws \Exception If the certificate could not get added
+	 * @throws \Exception If the certificate could not be added
 	 * @since 8.0.0 - since 8.1.0 throws exception instead of returning false
 	 */
 	public function addCertificate(string $certificate, string $name): \OCP\ICertificate;
 
 	/**
-	 * @param string $name
+	 * Remove a trusted certificate from the certificate store.
+	 *
+	 * @param string $name The filename for the certificate
 	 * @return bool
 	 * @since 8.0.0
 	 */
 	public function removeCertificate(string $name): bool;
 
 	/**
-	 * Get the path to the certificate bundle
+	 * Get the relative path to the generated certificate bundle.
 	 *
 	 * @return string
 	 * @since 8.0.0
 	 */
 	public function getCertificateBundle(): string;
 
 	/**
-	 * Get the full local path to the certificate bundle
+	 * Get the full local path to the effective certificate bundle.
+	 *
+	 * Implementations should return the generated bundle path, but may log and fall back
+	 * to the shipped default CA bundle if resolution fails.
 	 *
 	 * @return string
 	 * @since 9.0.0
 	 */
 	public function getAbsoluteBundlePath(): string;
 
 	/**
-	 * Get the path of the default certificates bundle.
+	 * Get the path of the shipped default certificates bundle.
 	 *
 	 * @since 33.0.0
 	 */