[WFCORE-4484] Support SSH Authentication for Git persistence

elytron/WFCORE-4484-ssh-authentication-git-persistence.adoc

@@ -0,0 +1,145 @@
+= [WFCORE-4484] Support SSH authentication for Git persistence
+:author:            Ashley Abdel-Sayed
+:email:             aabdelsa@redhat.com
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+
+== Overview
+
+When using a Git repository to manage your WildFly configuration file history, it is possible to use an Elytron
+configuration file for authentication. However, it is currently only possible to specify credentials to authenticate
+with HTTP, not SSH, even though Git supports SSH authentication. This proposal is to add support for SSH authentication
+for Git persistence using an Elytron configuration file.
+
+It will be possible for users to specify the location, filename, and passcode to an existing SSH private key to use
+as credentials for SSH authentication.
+
+It will also be possible for users to specify the keys to be used for authentication as KeyPairCredentials. This will mean
+supporting specifying KeyPairCredentials in an Elytron configuration file as a credential or as a reference to an entry in
+a CredentialStore. This will require modifying the `key-pair` credential to accept the OpenSSH
+https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key[private key] format.
+
+The `key-pair` credential currently supports keys using the RSA, DSA, and ECDSA algorithms, and this feature will add
+support for the ED25519 algorithm. The user should then be able to configure their WildFly standalone server to connect to
+a Git repo and authenticate with SSH to manage their configuration file history.
+
+== Issue Metadata
+
+=== Issue
+
+* https://issues.jboss.org/browse/WFCORE-4484[WFCORE-4484]
+
+=== Related Issues
+
+* https://issues.jboss.org/browse/EAP7-1213[EAP7-1213]
+* https://issues.jboss.org/browse/WFLY-12574[WFLY-12574]
+* https://issues.jboss.org/browse/ELY-1879[ELY-1879]
+
+=== Dev Contacts
+
+* mailto:{email}[{author}]
+
+=== QE Contacts
+TBD
+
+=== Testing By
+// Put an x in the relevant field to indicate if testing will be done by Engineering or QE.
+// Discuss with QE during the Kickoff state to decide this
+[ ] Engineering
+
+[ ] QE
+
+=== Affected Projects or Components
+
+=== Other Interested Projects
+
+== Requirements
+
+=== Hard Requirements
+
+==== JGit/SSHD
+* It will be possible to connect to a remote git repo and authenticate using Elytron with SSH to manage the Git configuration
+file history. This will be done using the Apache Mina SSHD session factory supported by JGit
+
+==== Elytron Tool
+
+The following commands will be added to the Elytron tool for offline CredentialStore manipulation:
+
+* `--generate-key-pair` - this will generate a private and public key pair and store them in a credential store. It will
+have the following options:
+** `--algorithm` - mandatory, indicates the algorithm to be used to generate the keys: RSA, DSA, ECDSA, or EDDSA
+** `--size` - the size of the key, only specified for RSA algorithm, by default is 2048 for RSA (the size is always 1024
+for DSA)
+** `--passphrase` - an optional passphrase to be used to encode the key
+** `--alias` - the alias to store the key under
+
+* `--import-key-pair` - this will import a private key and store it in a credential stores. It will have the following
+options:
+** `--private-key` - the private key to import as a String, mandatory if `--private-key-location` is
+not defined
+** `--private-key-location` - the path to and identity of the key (eg. ~/.ssh/id_rsa),  mandatory if `--private-key`
+is not defined
+** `--passphrase` - an optional passphrase used to encode the private key
+** `--algorithm` - the algorithm used to generate the keys
+** `--alias` - the alias to store the KeyPair under
+
+NOTE: The public key can be extracted from the encoded private key and a complete KeyPairCredential can be created.
+
+* `--export-public-key` - this will return a single Base64 value which is the public key in it’s OpenSSH encoded form. It will
+have the following options:
+** `--alias` - the alias the KeyPair is stored under
+
+==== Elytron XML File
+
+* It will be possible to specify SSH credentials to be used for authentication in the Elytron XML configuration file
+** There will be the option to specify an `openssh-private-key` under the existing `key-pair` credential. This will parse
+a private key encoded in OpenSSH format and generate the public and private keys in a KeyPairCredential.
+** There will be the option to reference a KeyPairCredential stored in a CredentialStore
+** It will be possible to specify the location and identity of a private key (eg. ~/.ssh/id_rsa). The user will also
+be able to specify the passphrase used to encode the key as a `clear-password`, `masked-password`, or `credential-reference`.
+
+NOTE: If no credentials are specified, authentication will be attempted with the default location `~/.ssh` and default
+filenames: `id_rsa, id_dsa, id_ecdsa, id_ed25519`
+
+=== Nice-to-Have Requirements
+
+=== Non-Requirements
+
+== Test Plan
+
+==== JGit/SSHD
+
+* Tests will be added to the WildFly-Core testsuite to test SSH authentication when connecting to a Git repository
+** Tests will be added to test successful authentication when using the default key location and file names
+** Tests will be added to test successful authentication when specifying the location, name, and passphrase to the file
+containing a private key
+** Tests will be added to test successful authentication using a KeyPairCredential with all supported algorithm types
+** Tests will be added to test unsuccessful authentication when no correct credentials are provided
+
+==== Elytron Tool
+
+* Tests will be added to the Elytron testsuite to test generating and importing a KeyPairCredential successfully into
+ a CredentialStore with all supported algorithms
+
+==== Elytron XML File
+* Tests will be added to the Elytron testsuite to test parsing an SSH credential specified as a location, name and passphrase
+of a file
+* Tests will be added to test parsing of a `key-pair` credential type in the OpenSSH format for all supported algorithms
+
+== Community Documentation
+
+* Documentation will be added to https://github.com/wildfly/wildfly/blob/master/docs/src/main/asciidoc/_admin-guide/management-tasks/Configuration_file_git_history.adoc[Git Configuration File History]
+under a new section SSH Authentication detailing how to configure SSH authentication with the different possible credential
+configurations.
+* Documentation will be added to https://github.com/wildfly/wildfly/blob/master/docs/src/main/asciidoc/_elytron/Credential_Store.adoc[Credential Store]
+to describe the new options to generate and import KeyPairCredentials
+* Documentation will be added to https://github.com/wildfly/wildfly/blob/master/docs/src/main/asciidoc/_elytron/Client_Authentication_with_Elytron_Client.adoc[Client Authentication with Elytron Client]
+to describe the changes to the KeyPairCredential and the new option to specify a private keys location as a credential.
+
+== Release Note Content
+
+Currently, WildFly users can use a Git repository to manage their configuration file history of their standalone server.
+While previously it was only possible to establish a connection with HTTP authentication, it is now possible to establish
+a connection with SSH authentication using an Elytron configuration file to specify the credentials to be used.