Analysis

Summary

The Elytron subsystem contains a key-store resource with operations that can be used for basic KeyStore manipulation (i.e., load, remove-alias, store, read-alias(es)). This task is to provide more advanced management operations for KeyStore manipulation. With these new operations, it should be possible to set up two-way SSL for applications and management interfaces using only management operations (using the keytool command will no longer be necessary).

Requirements

Hard requirements

• Additional runtime-only management operations should be added to the key-store resource in the Elytron subsystem in order to:
  • Generate a key pair
    • generate-key-pair --alias=<alias> --distinguished-name=<distinguishedName> [--algorithm=<keyAlgorithmName>] [--signature-algorithm=<signatureAlgorithmName>] [--key-size=<keySize>] [--not-before=<yyyy-MM-dd HH:mm:ss>] [--validity=<validity>] [--extensions=[{critical=<true,false>, name=<extensionName>,value=<extensionValue>}...] [--credential-reference=<key password>]
      • Allowed values for extensionName and extensionValue can be found here

• Generate a certificate signing request (as specified in RFC 2986)
  • generate-certificate-signing-request --alias=<alias>  --path=/path/to/output.csr [--signature-algorithm=<signatureAlgorithmName>] [--distinguished-name=<distinguishedName>] [--extensions=[{critical=<true,false>, name=<extensionName>,value=<extensionValue>}...] [--credential-reference=<key password>] [--relative-to=<dir variable>]
    • Allowed values for extensionName and extensionValue can be found here

• Import an X.509 certificate or certificate chain from a file
  • A certificate chain should be able to be specified as either a PKCS#7 formatted certificate reply or as a sequence of X.509 certificates
  • Supported file formats: Binary encoding and printable encoding
  • import-certificate --alias=<alias> --path=/path/to/certificate.cert [--credential-reference=<key password>] [--relative-to=<dir variable>] [--trust-cacerts=<true,false>] [--validate=<true,false>]
    • The trust-cacerts parameter specifies whether certificates from the cacerts file should be included when creating / validating the certificate chain.
    • The validate parameter specifies whether to validate that the top-most certificate is actually trusted when importing a certificate chain or whether to validate the certificate is actually trusted when importing a trusted certificate. The default value is true. When this is set to true and validation fails, the certificate or certificate chain will not be imported into the KeyStore.

• Export an X.509 certificate to a file
  • Supported file formats: Binary encoding and printable encoding
  • export-certificate --alias=<alias> --path=/path/to/output.cert [--relative-to=<dir variable>] [--pem=<true,false>]
    • The pem parameter specifies whether to export the certificate in printable encoding format. If not specified, the certificate will be exported in binary encoding format.

• Change an existing alias

  • change-alias --alias=<alias> --new-alias=<newAlias> [--credential-reference=<key password>]

• These operations should not be registered on managed domain profile resources.
• These operations should support the standard key algorithms, the standard signature algorithms, and the standard types of keystores as specified below:

  • http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyPairGenerator

  • http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#Signature
  • https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyStore

• These operations should only be available for the /subsystem=elytron/key-store resource, which is a file-backed resource. It does not make sense to make these operations available for the /subsystem=elytron/filtering-key-store resource since this resource is meant for exposing a subset of aliases from an existing KeyStore, not for making changes to it.

Nice-to-have requirements

• Make the new operations available for the /subsystem=elytron=ldap-key-store resource as well (an ldap-key-store uses a KeyStore that's stored in an LDAP server).

Non-requirements

• Atomic updates coordinated by the Domain Controller of multiple servers in a managed domain.

Design Notes

After generating a key pair, importing a certificate from a file, or changing an existing alias, the key-store "store" management operation will need to be executed in order to save the resulting changes to the file that backs the key-store. This is how persisting changes after removing an alias from a key-store currently works.

General

Tracking Issues

Main tracking issue - WFCORE-3305

Developer Resources

Elytron subsystem:

https://github.com/wildfly/wildfly-core/tree/master/elytron

Developer Contacts

Farah Juma - fjuma@redhat.com