SSL commands for CLI
Analysis
Summary
Offer a set of commands to enable/disable SSL for management interfaces and undertow http-server.
Requirements
Hide and group the set of low level DMR operations exposed by elytron resources to achieve SSL enablement/disablement on management interfaces and web server.
Design Notes
Although the http part (or native interface) is not elytron related, making a single command that group both elytron and management interfaces (or undertow server) configuration seems to make sense.
These actions would hide part of the complexity (eg: naming and creating new elytron resources) and properly sequence operations. They have a limited set of required options, full power being offered by optional options with some default values. Completion should be very useful there.
The enable commands allow to enable SSL in 3 way:
- Relying on the new operations exposed by elytron to generate key pairs. Operations are defined in Analysis and Design document
- Using an the key-store-name of an already added key-store
- Using a key-store file (so not already added to the model).
The disable commands are erasing the references to SSLContext but are not deleting any resource.
The DMR operations would be put in a batch in order to avoid side effects in case of error. Any error encountered while building-up the batch would abort the command (eg: invalid key-store type, already-exiting key-store, ...). Until WFCORE-3491 is not fixed, the key-store and trust-store will be created prior to have trust-store and key-store be generated.
The security commands are exposed by completion only if the CLI is connected to a managed process (or embedded server) that supports elytron and is not a host controller. The commands that target undertow are only available if the undertow subsystem is present.
Security considerations
Some key-store and trust-store passwords can be generated on the client side and sent to the server through insecure connection. Passwords are stored as clear-test on the server, no credential stores.
Backward compatibility
The SSL commands will be only available if CLI detects that the elytron subsystem is present in the managed process (or embedded server) to which it is connected. In addition, the use-cases that rely on some elytron operations unavailable in the process are hidden (--interactive and --trusted-certificate-path). The help content must be clear on this.
Domain mode considerations
These commands are not supported in domain mode. They only target standalone server. The help content must be clear on this.
Server reload
When the server is reloaded (when no --no-reload option is in use), the start-mode of the reload operation is aligned with the current running-mode of the connected managed process. For example, if the running-mode is ADMIN_ONLY, then the reload will be done with a start-mode=admin-only.
General
enable-ssl-management action
security enable-ssl-management ( [--interactive] |
[--key-store-path=<key-store path>]
[--key-store-password=<password>]
[--key-store-path-relative-to=<system
property>] [--key-store-type=<type>]
[--new-key-store-name=<key-store name>] |
[--key-store-name=<key-store name>] )
[--management-interface=<management
interface>]
[--http-secure-socket-binding=<socket
binding>]
[--new-key-manager-name=<key-manager name>]
[--new-ssl-context-name=<ssl-context name>]
[--no-reload] ( [--trust-store-name=<name>]
| [--trusted-certificate-path=<certificate
path>] [--new-trust-store-name=<a string>]
[--no-trusted-certificate-validation]
[--trust-store-file-name=<file name>]
[--trust-store-file-password=<password>] )
[--new-trust-manager-name=<a string>]
Minimal set of options to enable https for the management http-interface would be:
security enable-ssl-management --interactive
In this case, CLI prompts the user for a possible key-store file name (by default management.keystore is used), DN (with wizard to help user complete DN), password (by default generated), alias (by default generated), validity (by default generated), Mutual (by default no mutual), client certificate path (CLI offers file completion for this value), trust-store file name (by default management.truststore), password (by default generated), validate certificate (by default validated).
Once these pieces of information are collected, the server keystore (RSA, key-size 1024), the certificate (in pem format) files and optionally the trust-store files are generated in the server configuration directory. In case an elytron key-store resource already references the same file in the same location, the command is aborted and the user is suggested to change the file name or use the --key-store-name option to reuse the existing key-store.
key-store, key-manager, trust-manager and ssl-context are generated and the http-interface is secured. NB: this command is to be used in interactive mode only.
Minimal set of options to enable https for the management http-interface using an already added key-store and have the standalone server to reload would be:
security enable-ssl-management --key-store-name=<ksname>
Minimal set of options to enable https for the management http-interface using key-store file and have the standalone server to reload would be:
security enable-ssl-management --key-store-path=<path to keystore> --key-store-password=<password>
disable-ssl-management action
Remove the SSL Context (and possibly http-secure-socket-binding) from the selected management interface. NB: Some special logic is added to this CLI command in order to be able to reconnect after the https connection has been removed.
security disable-ssl-management [--management-interface=<interface>] [--no-reload]
enable-ssl-http-server action
security enable-ssl-http-server ( [--interactive] |
[--key-store-path=<key-store path>]
[--key-store-password=<password>]
[--key-store-path-relative-to=<system
property>] [--key-store-type=<type>]
[--new-key-store-name=<key-store name>] |
[--key-store-name=<key-store name>] )
[--new-key-manager-name=<key-manager name>]
[--new-ssl-context-name=<ssl-context name>]
[--no-override-security-realm]
[--no-reload] ( [--trust-store-name=<name>]
| [--trusted-certificate-path=<certificate
path>] [--new-trust-store-name=<a string>]
[--no-trusted-certificate-validation]
[--trust-store-file-name=<file name>]
[--trust-store-file-password=<password>] )
[--new-trust-manager-name=<a string>]
[--server-name=<server name>]
Minimal set of options to enable https for the default server:
security enable-ssl-http-server --interactive
The behaviour is similar to the management command. The default key-store name is <server name>.keystore, the default trust-store name is <server name>.truststore.
Minimal set of options to enable https for the default server:
security enable-ssl-http-server --key-store-name=name
Minimal set of options to enable https for the default server using key-store file and have the standalone server to reload would be:
security enable-ssl-http-server --key-store-path=<path to keystore> --key-store-password=<password>
http-server-disable-ssl action
Remove the SSL Context from the selected server and set the legacy-realm to be the out of the box ApplicationRealm.
security http-server-disable-ssl [--server-name=<server name>] [--no-reload]
Options
Interactive mode:
--interactive=To start a wizard that prompts the user to get all the required pieces of information. The only other optional available options are --management-interface, --http-secure-socket-binding, --server-name and --no-reload
Enable SSL using an exiting key-store resource use-case:
--key-store-name=The name of a an existing key-store.. Can't be used with --key-store-path. Completion lists existing key-store.
Enable SSL using an existing key-store file use-case:
--key-store-path=The path (absolute or relative) to a key-store, can't be used with --key-store-name. Completion lists existing files.
--key-store-type=Only available if --keystore-path is used.Type of key-store, by default is JKS.
--key-store-path-relative-to=Only available if --keystore-path is used. Specify a server system property (e.g.: jboss.server.config.dir).
--key-store-password=Only available if --keystore-path is used.The keystore password.
--new-key-store-name=Only available if --keystore-path is used. If not set, computed on the fly. If the resource already exists, the command is aborted. When set, a new resource is created, no reuse of existing resource.
Options common to all use-cases:
--new-key-manager-name=If not set, computed on the fly. If the resource already exists, the command is aborted. When set, a new resource is created, no reuse of existing resource.
--new-ssl-context-name=If not set, computed on the fly. If the resource already exists, the command is aborted. When set, a new resource is created, no reuse of existing resource.
--no-reload if not in use, the command reloads the server
Two way authentication by importing trusted-certificate use-case:
--trusted-certificate-path=Absolute path to client certificate to import. Optional, can't be used with --trust-store-name. Completion lists existing files.
--trust-store-file-name=The name of the generated trust-store file. By default it is generated.
--trust-store-file-password=The password of the generated trust-store file. By default it is generated.
--no-trusted-certificate-validation By default the certificate is validated, and the operation aborts if the validation fails. Use this option to disable validation.
--new-trust-store-name=If not set, computed on the fly. If the resource already exists, the command is aborted. When set, a new resource is created, no reuse of existing resource.
Two way authentication by referring an existing trust-store:
--trust-store-name=The name of the trust-store that contains the client certificate. Optional, can't be used with --trusted-certificate-path. Completion lists existing key-store.
Common to both Two way use-cases:
--new-trust-manager-name=If not set, computed on the fly. If the resource already exists, the command is aborted. When set, a new resource is created, no reuse of existing resource.
Options specific to management use-case:
--management-interface=If not set, use http-interface. Completion lists existing management interfaces.
--http-secure-socket-binding=If not set and --management-interface is http-interface use management-https, if it doesn't exist or --management-interface is not http-interface, abort. Completion lists existing socket bindings.
Options specific to http-server use case:
--server-name=If not set, default-server is used. Completion lists existing servers.
--no-override-security-realm, if not in use security-realm is erased, if used, the command would fail if the https-listener is configured to use legacy.
Product Issue(s)
https://issues.jboss.org/browse/EAP7-702
https://issues.jboss.org/browse/EAP7-650
Upstream Issue(s)
[WFCORE-3447] CLI SSL security commands. - JBoss Issue Tracker
[WFCORE-3305] Advanced Elytron key-store manipulation operations - JBoss Issue Tracker
Developer Contacts
Jean-François Denise (jdenise@redhat.com)
Comments