CAMEL-23806: Split mina-sftp docs into focused sub-pages

components/camel-mina-sftp/src/main/docs/mina-sftp-authentication.adoc

@@ -0,0 +1,208 @@
+= MINA SFTP Authentication
+:tabs-sync-option:
+
+xref:ROOT:mina-sftp-component.adoc[Back to MINA SFTP Component]
+
+The MINA SFTP component supports multiple authentication methods.
+
+== Password Authentication
+
+[source,java]
+----
+from("mina-sftp://admin@host/path?password=secret")
+    .to("file:local");
+----
+
+== Public Key Authentication
+
+=== Using Private Key File
+
+[source,java]
+----
+from("mina-sftp://user@host/path?privateKeyFile=/home/user/.ssh/id_rsa")
+    .to("file:local");
+----
+
+=== Using Private Key from Classpath
+
+[source,java]
+----
+from("mina-sftp://user@host/path?privateKeyUri=classpath:keys/id_rsa")
+    .to("file:local");
+----
+
+=== Using Encrypted Private Key
+
+[source,java]
+----
+from("mina-sftp://user@host/path?privateKeyFile=/path/to/encrypted_key&privateKeyPassphrase=mypassphrase")
+    .to("file:local");
+----
+
+=== Using Direct KeyPair Object
+
+[source,java]
+----
+KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
+keyGen.initialize(2048);
+KeyPair keyPair = keyGen.generateKeyPair();
+
+MinaSftpEndpoint endpoint = context.getEndpoint(
+    "mina-sftp://user@host/path", MinaSftpEndpoint.class);
+MinaSftpConfiguration config = (MinaSftpConfiguration) endpoint.getConfiguration();
+config.setKeyPair(keyPair);
+----
+
+== Authentication Priority
+
+When both password and public key authentication are configured, the component tries public key first and falls back to password. This matches the JSch-based sftp component.
+
+== Preferred Authentication Methods
+
+Customize the authentication order using `preferredAuthentications`:
+
+[source,java]
+----
+from("mina-sftp://user@host/path?password=secret&privateKeyFile=/path/to/key&preferredAuthentications=password,publickey")
+    .to("file:local");
+----
+
+[cols="2,4"]
+|===
+| Method | Description
+
+| `publickey`
+| Public key or certificate-based authentication
+
+| `password`
+| Password-based authentication
+
+| `keyboard-interactive`
+| Keyboard-interactive authentication (multi-factor scenarios)
+|===
+
+If not specified, the default order from Apache MINA SSHD is used: publickey, keyboard-interactive, password.
+
+== Public Key Accepted Algorithms
+
+Restrict which public key algorithms are accepted using `publicKeyAcceptedAlgorithms`:
+
+[source,java]
+----
+from("mina-sftp://user@host/path?privateKeyFile=/path/to/key&publicKeyAcceptedAlgorithms=ssh-ed25519,rsa-sha2-256,rsa-sha2-512")
+    .to("file:local");
+----
+
+[cols="2,4"]
+|===
+| Algorithm | Description
+
+| `ssh-ed25519`
+| Ed25519 algorithm (modern, recommended)
+
+| `rsa-sha2-256`
+| RSA with SHA-256 signature (recommended)
+
+| `rsa-sha2-512`
+| RSA with SHA-512 signature (recommended)
+
+| `ecdsa-sha2-nistp256`
+| ECDSA with NIST P-256 curve
+
+| `ecdsa-sha2-nistp384`
+| ECDSA with NIST P-384 curve
+
+| `ecdsa-sha2-nistp521`
+| ECDSA with NIST P-521 curve
+
+| `ssh-rsa`
+| Legacy RSA with SHA-1 (avoid if possible)
+
+| `ssh-dss`
+| DSA algorithm (deprecated)
+|===
+
+== Supported Key Formats
+
+The component supports all key formats natively supported by Apache MINA SSHD:
+
+* **PEM formats**: PKCS#1, PKCS#8, OpenSSH format
+* **OpenSSH native format**
+* **Encrypted keys**: Supported (PKCS#8 encrypted requires BouncyCastle)
+
+Supported key algorithms: RSA (all key sizes), ECDSA (P-256, P-384, P-521), Ed25519, DSA.
+
+== Client Certificate Authentication
+
+The mina-sftp component supports OpenSSH certificate-based authentication, which provides centralized key management through a Certificate Authority (CA). This is a MINA SSHD-specific feature not available in the JSch-based sftp component.
+
+OpenSSH certificates bind a public key to identity information and are signed by a trusted CA. They provide centralized key revocation, time-limited access without key rotation, and principal-based authorization.
+
+=== Certificate Options
+
+[cols="2,3,1"]
+|===
+| Option | Description | Priority
+
+| `certBytes`
+| Certificate content as byte array (for programmatic loading from secret managers)
+| 1 (highest)
+
+| `certUri`
+| URI to certificate file (classpath:, file:, etc.)
+| 2
+
+| `certFile`
+| Path to certificate file on filesystem
+| 3 (lowest)
+|===
+
+The first non-empty option wins. This matches the priority order used for private key options (`privateKey` > `privateKeyUri` > `privateKeyFile`).
+
+=== Certificate Format Requirements
+
+* Certificates must be in OpenSSH format (as generated by `ssh-keygen -s`)
+* Only USER type certificates are supported (for client authentication)
+* The certificate must correspond to the configured private key
+* Certificate file typically has a `-cert.pub` suffix (e.g., `id_rsa-cert.pub`)
+
+=== Example: Certificate from File
+
+[source,java]
+----
+from("direct:start")
+    .to("mina-sftp://user@host/path?privateKeyFile=/path/to/id_rsa&certFile=/path/to/id_rsa-cert.pub");
+----
+
+=== Example: Certificate from Classpath
+
+[source,java]
+----
+from("direct:start")
+    .to("mina-sftp://user@host/path?privateKeyUri=classpath:keys/id_rsa&certUri=classpath:keys/id_rsa-cert.pub");
+----
+
+=== Example: Certificate from Byte Array
+
+[source,java]
+----
+// Load certificate from external secret manager
+byte[] certBytes = secretManager.getCertificate("sftp-cert");
+byte[] keyBytes = secretManager.getPrivateKey("sftp-key");
+
+MinaSftpEndpoint endpoint = context.getEndpoint(
+    "mina-sftp://user@host/path", MinaSftpEndpoint.class);
+MinaSftpConfiguration config = (MinaSftpConfiguration) endpoint.getConfiguration();
+config.setCertBytes(certBytes);
+config.setPrivateKey(keyBytes);
+----
+
+=== Certificate Validation
+
+The component validates certificates before use:
+
+* **Type check**: Only USER certificates are accepted (not HOST certificates)
+* **Validity period**: Certificate must be currently valid (not expired, not before valid-from date)
+* **Private key requirement**: A corresponding private key must be configured
+
+Invalid certificates result in clear error messages indicating the issue.