Repository files navigation

This is a script automation for the generation of the requiredkeystores,truststores and browsercertificates for Alfresco configuration using Mutual TLS Authentication between Repository and SOLR. These same files can be obtained manually by using any other cryptographic tools.

This project is not officially supported by Alfresco, as it provides just a sample to build your own security configuration for Alfresco. However, anyone can improve this tool by providing pull requests or by cloning the project and changing it accordingly to suit particular needs.

As HTTPs invocations happen between different Alfresco services, following relationships must be satisfied:

• Repository is client of SOLR and Transform Services

  • Repository key must be generated and must be included inRepository keystore
  • Root CA certificate must be included inRepository truststore

• SOLR is client of Repository and SOLR

  • SOLR key must be generated and must be included inSOLR keystore
  • Root CA certificate must be included inSOLR truststore

• Zeppelin is client of Repository (Zeppelin is a product only available for Insight Engine Enterprise)

  • Zeppelin key must be generated and must be included inZeppelin keystore
  • Root CA certificate must be included inZeppelin truststore
  • Note that this script tool uses the same key certificates for SOLR and Zeppelin, as both are clients of the Repository

• When accessing SOLR from a browser, the browser is client of SOLR

  • Browser key must be installed on the browser in order to access SOLR Web Console

• Transform Services (Transform Router, T-Engines, Transform Aspose, AI Renditions, Shared File Store)

  • Transform Service key must be generated and must be included inTransform Service keystore for every Transform Service present
  • Root CA certificate must be included inTransform Service truststore for every Transform Service present

Additionally, to support Alfrescoencryption feature, a metadata cyphering key is generated and included on akeystore to be used by the Repository.

Certificates generation scriptrun.sh is based inOpenSSL and Javakeytool programs, and it can be used in different scenarios:

• Bash Shell Script Standalone, as a local bash script from Linux operative systems. The shell script and the OpenSSL configuration file are available inssl-tool folder.
• Windows Batch Script Standalone, as a local batch script from Windows operative systems. The batch script and the OpenSSL configuration file are available inssl-tool-win folder.
• Docker Standalone, as a local container generatingkeystores folder from environment variable values. Available from Linux, Windows and Mac OS X.
• Docker Compose, as a Docker service creatingkeystores folder from environment variable values. Available from Linux, Windows and Mac OS X.

New certificates generation scriptsrun_ca.sh,run_encryption.sh andrun_additional.sh have been created to respond to the need of adding a varying number of additional services to mTLS. They also provide more granularity and control over passwords and other settings. They are currently unavailable for use inDocker Standalone andDocker Compose

Running the generation script requires havingOpenSSL and Javakeytool programs installed and available in the system path.

OpenSSL

OpenSSL is a cryptographic software to generate certification authorities, private keys and certificates (including usage policies).

Many distributions ofLinux includeOpenSSL as a package, so you can install it as any other program.

Ubuntu

$ sudo apt-get install openssl

CentOS

$ yum -y install openssl openssl-devel

ForMac OS X, some package manager likeHomebrew can be used:

$ brew install openssl

When usingWindows, binaries distribution from OpenSSL web page can be used:

https://wiki.openssl.org/index.php/Binaries

Remember to addopenssl program to system path.

Keytool

Keytool is a standard Java program to buildkeystores andtruststores.

The keytool utility is included with the JRE.

Both Oracle JRE 11 and OpenJDK JRE 11 can be used, just follow the installation instructions for your operative system.

Remember to addkeytool program to system path.

Both command line scripts and Docker Image resources can be parametrised by using external parameter values. Different options are described in the table below.

When using Alfresco on an internal network, each server should have a different name. This names can be configured on the parameters named as*servername. In order to avoid browser complains about certificates, it's recommended to include the name of the server asAlternative Name in the certificate. This should be at least required for SOLR Web Console, as this application is only available inhttps when using this configuration. If you are working under a Web Proxy, use the name of this proxy for the*servername parameters.Scripts have been updated to handle multiple Service Alternative Names. To provide multiple of them seperate them with,, example:-servername localhost,additionalSAN. For Windows variant the value needs to be enclosed in double quotes.

When working on aLinux machine, shell scripts can be used directly from command line. It's required to haveOpenSSL andkeytool programs available in the environment.It is recommended to use the latest versions of these programs when possible.

The scripts parameters can be set through command line.

For instance, the following command will producekeystores folder in a host folder namedkeystores using RSA key length of 2048 bits for Alfresco Enterprise.

$cd ssl-tool$ ./run.sh -keysize 2048 -alfrescoversion enterprise -alfrescoformat classic$ tree keystores/keystores/├── alfresco│   ├── keystore│   ├── keystore-passwords.properties│   ├── ssl-keystore-passwords.properties│   ├── ssl-truststore-passwords.properties│   ├── ssl.keystore│   └── ssl.truststore├── client│   └── browser.p12├── solr│   ├── ssl-keystore-passwords.properties│   ├── ssl-truststore-passwords.properties│   ├── ssl.repo.client.keystore│   └── ssl.repo.client.truststore└── zeppelin    ├── ssl.repo.client.keystore    └── ssl.repo.client.truststore

When using customDNames for certificates, values must be set in quotes.

$ ./run.sh -cacertdname"/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Linux Alfresco CA" \-repocertdname"/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Repo" \-solrcertdname"/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Solr" \-browsercertdname"/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Browser"

Note that whenkeystores folder is not empty, the program exists without producing any keystore or truststore.

When usingcurrent Alfresco format (default option), instead ofclassic, following output is generated.

$cd ssl-tool$ ./run.sh -keysize 2048 -alfrescoversion enterprise$ tree keystores/keystores/├── alfresco│   ├── keystore│   ├── ssl.keystore│   └── ssl.truststore├── client│   └── browser.p12├── solr│   ├── ssl-repo-client.keystore│   └── ssl-repo-client.truststore└── zeppelin    ├── ssl-repo-client.keystore    └── ssl-repo-client.truststore

For thecurrent format all the passwords are passed to the applications using Java Environment Variables, so the password files are not required any more.

If you desire more control and granularity, or need to add other services into the mTLS mix, then you might want to consider usingrun_ca.sh,run_encryption.sh andrun_additional.sh in place ofrun.sh script or onlyrun_additional.sh as an addition.run_ca.sh - script responsible for preparing folders (ca, certificates, keystores) and generating the Root CA,run_encryption.sh - script responsible for generating the metadata encryption keystorerun_additional.sh - script using the previously generated CA (withrun.sh orrun_ca.sh script) to generate additional sets of keystore and truststore.

Samples of using these scripts and how they replace therun.sh functionality or add on to it can be found inssl-tool\samples folder of this project.Keep in mind that some locations of generated scripts or names of keystores might differ between the samples of new approach (run_ca.sh +run_encryption.sh +run_additional.sh) and legacy approach (run.sh +run_additional.sh).

If you'd like to restrict the certificates provided to a truststore, to pick and choose between which ones should be added to which service, you can do that by adding to the command ofrun_additional.sh script the-notruststore flag.This flag causesrun_additional.sh script to not generate a truststore on its own. Afterwards you can write your own instructions to generate a truststore by picking certificates from thecertificates folder that would end up in it after running the scripts.Sample command that would create a truststore for Solr that contains only the Repository certificate:keytool -importcert -noprompt -alias alfresco -file certificates/alfresco.cer -keystore keystores/solr/solr.truststore -storetype JCEKS -storepass password

You can add more certificates this way.

When working on aWindows machine, shell scripts can be used directly from command line. It's required to haveOpenSSL andkeytool programs available in thePATH.It is recommended to use the latest versions of these programs when possible.

The parameters described above, can be used from command line.

For instance, the following command will producekeystores folder in a host folder namedkeystores using RSA key length of 2048 bits for Alfresco Community.

C:\>cd ssl-tool-winC:\> run.cmd -keysize 2048 -alfrescoversion community -alfrescoformat classicC:\> tree /F keystores├───alfresco│       keystore│       keystore-passwords.properties│       ssl-keystore-passwords.properties│       ssl-truststore-passwords.properties│       ssl.keystore│       ssl.truststore│├───client│       browser.p12│└───solr        ssl-keystore-passwords.properties        ssl-truststore-passwords.properties        ssl.repo.client.keystore        ssl.repo.client.truststore

When using customDNames for certificates, values must be set in quotes.

C:\> run.cmd -cacertdname"/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Windows Alfresco CA" ^-repocertdname"/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Repo" ^-solrcertdname"/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Solr" ^-browsercertdname"/C=GB/ST=UK/L=Maidenhead/O=Alfresco/OU=Unknown/CN=Browser"

Note that whenkeystores folder is not empty, the program exists without producing any keystore or truststore.

When usingcurrent Alfresco format (default option), instead ofclassic, following output is generated.

C:\>cd ssl-tool-winC:\> run.cmd -keysize 2048 -alfrescoversion communityC:\> tree /F keystores├───alfresco│       keystore│       ssl.keystore│       ssl.truststore│├───client│       browser.p12│└───solr        ssl.repo.client.keystore        ssl.repo.client.truststore

For thecurrent format all the passwords are passed to the applications using Java Environment Variables, so the password files are not required any more.

If you desire more control and granularity, or need to add other services into the mTLS mix, then you might want to consider usingrun_ca.cmd,run_encryption.cmd andrun_additional.cmd in place ofrun.cmd script or onlyrun_additional.cmd as an addition.run_ca.cmd - script responsible for preparing folders (ca, certificates, keystores) and generating the Root CA,run_encryption.cmd - script responsible for generating the metadata encryption keystorerun_additional.cmd - script using the previously generated CA (withrun.cmd orrun_ca.cmd script) to generate additional sets of keystore and truststore.

Samples of using these scripts and how they replace therun.cmd functionality or add on to it can be found inssl-tool-win\samples folder of this project.Keep in mind that some locations of generated scripts or names of keystores might differ between the samples of new approach (run_ca.cmd +run_encryption.cmd +run_additional.cmd) and legacy approach (run.cmd +run_additional.cmd).

If you'd like to restrict the certificates provided to a truststore, to pick and choose between which ones should be added to which service, you can do that by adding to the command ofrun_additional.cmd script the-notruststore flag.This flag causesrun_additional.cmd script to not generate a truststore on its own. Afterwards you can write your own instructions to generate a truststore by picking certificates from thecertificates folder that would end up in it after running the scripts.Sample command that would create a truststore for Solr that contains only the Repository certificate:keytool -importcert -noprompt -alias alfresco -file certificates/alfresco.cer -keystore keystores/solr/solr.truststore -storetype JCEKS -storepass password

You can add more certificates this way.

In order to access to SOLR Web Console, available by default athttps://localhost:8983/solr, browser certificate must be installed in your machine.

ForWindows systems,client\browser.p12 file must be imported as new private certificate toWindows Certificates application.

ForMac OS X systems,client/browser.p12 file must be imported toKeychain Access application.

Also setting the right options in these application totrust in this certificate is required.

Once the certificate is installed, the following message should be showed by your browser when accessing to Solr Web Console:

Your connection is not privateAttackers might be trying to steal your information from localhost (for example, passwords, messages or credit cards). Learn moreNET::ERR_CERT_AUTHORITY_INVALID

As the certificate has been generated forlocalhost, this warning is expected. Just click onAdvanced >> Proceed and use your browser certificate to access Solr Web Console.

Building the Docker Image

This image depends on thealfresco-docker-base-java image, which is also available (privately) onQuay and (publicly) onDocker Hub.

To build this image, run the following script:

docker build -t alfresco/alfresco-base-ssl.

The image can be used viadocker run to create stores and certificates, using a host mounted folder to obtain these results.

Volumes

Following folders are available to be mounted on volumes:

• /keystores folder contains the keystores and truststores generated foralfresco,solr andzeppelin services
• /ca folder contains internal information (CRL, CA key...) used by the CA created with OpenSSL
• /certificates folder contains raw certificates used to build the keystores and the truststores

To obtain the required folder for Alfresco services, it's only required to mountkeystores folder. CA and certificates folder can be also mounted, but those files are not used for Alfresco configuration.

$ docker run -v$PWD/keystores:/keystores alfresco/alfresco-base-ssl$ tree keystoreskeystores├── alfresco│   ├── keystore│   ├── ssl.keystore│   └── ssl.truststore├── client│   └── browser.p12├── solr│   ├── ssl-repo-client.keystore│   └── ssl-repo-client.truststore└── zeppelin    ├── ssl-repo-client.keystore    └── ssl-repo-client.truststore

Parameters

Docker Container can be started using some of the parameters defined above.

For instance, the following command will producekeystores folder in a host folder namedkeystores using RSA key length of 2048 bits for Alfresco Enterprise.

$ docker run -v$PWD/keystores:/keystores -e KEY_SIZE=2048 -e ALFRESCO_VERSION=enterprise alfresco/alfresco-base-ssl

Note that whenkeystores folder is not empty, the program exists without producing any keystore or truststore.

This Docker Image can be used as a Docker Compose service, accepting the same parameters for environment variables described before.

For instance, the following command will producekeystores folder in a host folder namedkeystores using RSA key length of 2048 bits for Alfresco Enterprise.

ssl:    image: alfresco/ssl-base    environment:        ALFRESCO_VERSION: enterprise        KEY_SIZE: 2048    volumes:        - ./keystores:/keystores

Sample configurations forAlfresco Enterprise andAlfresco Community have been provided atdocker-compose folder.

"SEC_ERROR_REUSED_ISSUER_AND_SERIAL" error when accessing SOLR Web Console in Firefox*

If you are using Alfresco SSL Generator for testing or developing and you issued the same CA Certificate more than one time, Firefox will complain when trying to access to SOLR Web Console (https://localhost:8983/solr by default).

This problem is described at Bugzilla:

https://bugzilla.mozilla.org/show_bug.cgi?id=435013

Apply any of the workarounds provided (as removingcert8.db orcert9.db file from your Firefox profile folder) in order to fix this problem.

When using certificates from external CAs, not the one provided by this project, building thekeystores andtruststores for Repository and SOLR is required.keytool or any other tool can be used in order to build these stores. Details on the content of every related file is available inAlfresco MTLS Configuration Deep Dive.

Note that every intermediate CA public key must be included in everytruststore.

keytool can be used to get this certificate chain.

$ keytool -list -alias alfresco.ca -keystore ssl.repo.client.keystore -rfcAlias name: alfresco.caCreation date: 20 Feb 2020Entry type: PrivateKeyEntryCertificate chain length: 2Certificate[1]:-----BEGIN CERTIFICATE-----MIIFNTCCBB2gAwIBAgIQDZAM1h0f9komm5D7ivokHTANBgkqhkiG9w0BAQsFADBeMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3d3cuZGlnaWNlcnQuY29tMR0wGwYDVQQDExRHZW9UcnVzdCBSU0EgQ0EgMjAxODAeFw0xODAxMDIwMDAwMDBaFw0yMTAxMDExMjAwMDBaMIGaMQswCQYDVQQGEwJVUzEQMA4GA1UECBMHSW5kaWFuYTEVMBMGA1UEBxMMSW5kaWFuYXBvbGlzMSwwKgYDVQQKEyNPbmVBbWVyaWNhIEZpbmFuY2lhbCBQYXJ0bmVycywgSW5jLjEZMBcGA1UECxMQTmV0d29yayBTZXJ2aWNlczEZMBcGA1UEAwwQKi5vbmVhbWVyaWNhLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALYdHOLovHc2j5xQfBngerSsIFJaVGOwsPQplUkQJ1P/V/gq9ihCtC/CqMFsQJRKJyoQ9Ii+CxsZLjeNVoPUl74AEoUXgO+Mv1BpEAdV0KvC8gF9jUk0Rv/u9Mebt08uoGPKW6bb+XkphboopwhqNt42Ypk6gwHW/HCyuCFXzWWT5ipcuK9vMpiNlZbBipicsX716AzYdOZ9uDSKpWbtxPriwsUeKbgkm5b2y3dH42bxjRs7ErNcVWF8jPiFUeDRFhA2gV2vbVfPr9jZV9be34xHJXv8O3SDLjgdvay5128jqOhHOt8seNVW6+I3qpWjePPwWZs+FrgcMwOxBO+S+CkCAwEAAaOCAbAwggGsMB8GA1UdIwQYMBaAFJBY/7CcdahRVHex7fKjQxY4nmzFMB0GA1UdDgQWBBRXtA41zjBtnwIQMyDegWj9frpzTjArBgNVHREEJDAighAqLm9uZWFtZXJpY2EuY29tgg5vbmVhbWVyaWNhLmNvbTAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMD4GA1UdHwQ3MDUwM6AxoC+GLWh0dHA6Ly9jZHAuZ2VvdHJ1c3QuY29tL0dlb1RydXN0UlNBQ0EyMDE4LmNybDBMBgNVHSAERTBDMDcGCWCGSAGG/WwBATAqMCgGCCsGAQUFBwIBFhxodHRwczovL3d3dy5kaWdpY2VydC5jb20vQ1BTMAgGBmeBDAECAjB1BggrBgEFBQcBAQRpMGcwJgYIKwYBBQUHMAGGGmh0dHA6Ly9zdGF0dXMuZ2VvdHJ1c3QuY29tMD0GCCsGAQUFBzAChjFodHRwOi8vY2FjZXJ0cy5nZW90cnVzdC5jb20vR2VvVHJ1c3RSU0FDQTIwMTguY3J0MAkGA1UdEwQCMAAwDQYJKoZIhvcNAQELBQADggEBACvC+8nlAtCo7AMSP0ajPyobbNGOg/IxgVIKzQV8mnAntxjWn+SqnHGeWMqhvbsAeRDWkDc/XDq4Qq+QJMDM2ZyePENGDnvVIjMPVHS+Nu1vc1JC9zn8vi9XKfB7OOcVOIJAp7ZZP9zAZLk79I0F6q6BeKj/d6myjEZO//4QLK5FA+Bz8Ah0XP5Nt90x+pPi76yRbUuxgkJd5va9JfX2GM5cpw/BphjNJeUhgFD8Gw8wxELwqNtc5QUlE0WlJSBrbRL9y+xuHcSYRlCsd3nEZ3h5PCtgjplziRxoB7R8KED+wH+MlWDSMbe+BtQ3rp9dPK2FYSZhQ3pIH4pR0+S+13Q=-----END CERTIFICATE-----Certificate[2]:-----BEGIN CERTIFICATE-----MIIEizCCA3OgAwIBAgIQBUb+GCP34ZQdo5/OFMRhczANBgkqhkiG9w0BAQsFADBhMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3d3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBDQTAeFw0xNzExMDYxMjIzNDVaFw0yNzExMDYxMjIzNDVaMF4xCzAJBgNVBAYTAlVTMRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5jb20xHTAbBgNVBAMTFEdlb1RydXN0IFJTQSBDQSAyMDE4MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAv4rRY03hGOqHXegWPI9/tr6HFzekDPgxP59FVEAh150Hm8oDI0q9m+2FAmM/n4W57Cjv8oYi2/hNVEHFtEJ/zzMXAQ6CkFLTxzSkwaEB2jKgQK0fWeQz/KDDlqxobNPomXOMJhB3y7c/OTLo0lko7geG4gk7hfiqafapa59YrXLIW4dmrgjgdPstU0Nigz2PhUwRl9we/FAwuIMIMl5cXMThdSBK66XWdS3cLX184ND+fHWhTkAChJrZDVouoKzzNYoq6tZaWmyOLKv23v14RyZ5eqoi6qnmcRID0/i6U9J5nL1krPYbY7tNjzgC+PBXXcWqJVoMXcUw/iBTGWzpwwIDAQABo4IBQDCCATwwHQYDVR0OBBYEFJBY/7CcdahRVHex7fKjQxY4nmzFMB8GA1UdIwQYMBaAFAPeUDVW0Uy7ZvCj4hsbw5eyPdFVMA4GA1UdDwEB/wQEAwIBhjAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwEgYDVR0TAQH/BAgwBgEB/wIBADA0BggrBgEFBQcBAQQoMCYwJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3NwLmRpZ2ljZXJ0LmNvbTBCBgNVHR8EOzA5MDegNaAzhjFodHRwOi8vY3JsMy5kaWdpY2VydC5jb20vRGlnaUNlcnRHbG9iYWxSb290Q0EuY3JsMD0GA1UdIAQ2MDQwMgYEVR0gADAqMCgGCCsGAQUFBwIBFhxodHRwczovL3d3dy5kaWdpY2VydC5jb20vQ1BTMA0GCSqGSIb3DQEBCwUAA4IBAQAw8YdVPYQI/C5earp80s3VLOO+AtpdiXft9OlWwJLwKlUtRfccKj8QW/Pp4b7h6QAlufejwQMb455OjpIbCZVS+awY/R8pAYsXCnM09GcSVe4ivMswyoCZP/vPEn/LPRhHhdgUPk8MlD979RGoUWz7qGAwqJChi28uRds3thx+vRZZIbEyZ62No0tJPzsSGSz8nQ//jP8BIwrzBAUH5WcBAbmvgWfrKcuv+PyGPqRcc4T55TlzrBnzAzZ3oClo9fTvO9PuiHMKrC6V6mgi0s2sa/gbXlPCD9Z24XUMxJElwIVTDuKB0Q4YMMlnpN/QChJ4B0AFsQ+DU0NCO+f78Xf7-----END CERTIFICATE-----

In the sample above,Certificate[2] content could be saved asalfresco-ca-root.cer to be imported in the repository truststore.