{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"bc6b0beb-f722-4917-a404-b9b1028ebb2e"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"d725d1e7-3cd0-4933-acc1-0e525a0cb60b"}},{"type":"heading","attrs":{"level":1},"content":[{"text":"Creating a Java KeyStore and SSL certificate","type":"text"}]},{"type":"paragraph","content":[{"text":"MettleCI Workbench can be configured to expose ports over HTTP, HTTPS, or both simultaneously at separate ports. Before configuring Workbench to use HTTPS, a ","type":"text"},{"text":"Java KeyStore","type":"text","marks":[{"type":"link","attrs":{"href":"https://en.wikipedia.org/wiki/Java_KeyStore"}}]},{"text":" containing the HTTPS certificate must be created first. Java KeyStores can be created and managed using the ","type":"text"},{"text":"keytool ","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html"}}]},{"text":"command included with all installations of Java. ","type":"text"}]},{"type":"paragraph","content":[{"text":"First ensure that you use the keytool command shipped with the ","type":"text"},{"text":"Java v1.8 package you downloaded to support MettleCI","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/MCIDOC/pages/488800406"}}]},{"text":". You can check which version of ","type":"text"},{"text":"keytool","type":"text","marks":[{"type":"code"}]},{"text":" is your command line's default by using the operating system-specific commands ","type":"text"},{"text":"where keytool","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"type":"status","attrs":{"color":"blue","style":"bold","text":"Windows","localId":"42a9fb96-54fa-4bfe-889b-f3f8240f7546"}},{"text":" or ","type":"text"},{"text":"which keytool","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"type":"status","attrs":{"color":"yellow","style":"bold","text":"Unix","localId":"3b8cb161-2064-4382-97e3-adc99175ebe4"}},{"text":". Verify that the response indicates that you will be using the keytool in the correct bin directory (e.g. in your OpenJDK installation).","type":"text"}]},{"type":"paragraph","content":[{"text":"Next, you’ll use the ","type":"text"},{"text":"keytool","type":"text","marks":[{"type":"code"}]},{"text":" command (with a format like that show below) to create a KeyStore that contains a single, basic, self-signed certificate:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"keytool -genkey -keyalg RSA -alias workbench -keystore \n -storepass -storetype PKCS12 -keysize 2048 \n -sigalg SHA256withRSA -dname \"CN=\"\n -ext san=dns:\n -validity ","type":"text"}]},{"type":"paragraph","content":[{"text":"Use the following table to replace the ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" in this example command with values that are specific to your environment and policies.","type":"text"}]},{"type":"table","attrs":{"layout":"default","localId":"1d3be04e-353d-4bcd-bf8d-9b6a018dda30"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[151.0]},"content":[{"type":"paragraph","content":[{"text":"Placeholder","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[427.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[946.0]},"content":[{"type":"paragraph","content":[{"text":"Example Value","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[151.0]},"content":[{"type":"paragraph","content":[{"text":"path-to-keystore","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[427.0]},"content":[{"type":"paragraph","content":[{"text":"Full qualified path of the key store to be created","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[946.0]},"content":[{"type":"paragraph","content":[{"text":"/opt/dm/mci/workbench.p12","type":"text","marks":[{"type":"code"}]},{"text":" (Unix) ","type":"text"}]},{"type":"paragraph","content":[{"text":"C:\\dm\\mci\\workbench.p12","type":"text","marks":[{"type":"code"}]},{"text":" (Windows)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[151.0]},"content":[{"type":"paragraph","content":[{"text":"store-password","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[427.0]},"content":[{"type":"paragraph","content":[{"text":"Password required when reading or writing to the newly created key store","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[946.0]},"content":[{"type":"paragraph","content":[{"text":"Choose a random password string.","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that the key stores supplied with Java have a default password of ","type":"text"},{"text":"changeit","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[151.0]},"content":[{"type":"paragraph","content":[{"text":"host-url","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[427.0]},"content":[{"type":"paragraph","content":[{"text":"The domain name of the URL that will be used to access Workbench in your browser. This does not include the protocol or port numbers. For example, ","type":"text"},{"text":"dev-engine.datamigrators.com","type":"text","marks":[{"type":"code"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[946.0]},"content":[{"type":"paragraph","content":[{"text":"your-engine.yourdomain.com","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"(no port number)","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[151.0]},"content":[{"type":"paragraph","content":[{"text":"days-valid","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[427.0]},"content":[{"type":"paragraph","content":[{"text":"The number of days for which the key should remain valid","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[946.0]},"content":[{"type":"paragraph","content":[{"text":"Note that the key stores supplied with Java have a default validity of 180 days.","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"For example, this command creates a keystore called ","type":"text"},{"text":"workbench.p12","type":"text","marks":[{"type":"code"}]},{"text":" in the MettleCI home directory for use with workbench currently accessed at URL ","type":"text"},{"text":"http://my-engine.datamigrators.com:8080","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"paragraph","content":[{"text":"This example generates a key with a 10-year validity.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"$> keytool -genkey -keyalg RSA -alias workbench -keystore workbench.p12 \\\n-storepass changeit -storetype PKCS12 -keysize 2048 \\\n-sigalg SHA256withRSA -dname \"CN=my-engine.datamigrators.com\" \\\n-ext san=dns:my-engine.datamigrators.com \\\n-validity 3650","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Note that in the example above you must ensure that both instances of ","type":"text"},{"text":"engine.datamigrators.com","type":"text","marks":[{"type":"code"}]},{"text":" are replaced with the domain name of ","type":"text"},{"text":"your","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" DataStage engine. It is suggested that you use the Workbench URL to derive this (e.g. ","type":"text"},{"text":"mydsengine.acmesandwichmakers.com","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]}]},{"type":"paragraph","content":[{"text":"You can verify your keystore by listing the certificates within it. You’ll need to re-enter your keystore password, which is 'changeit' (no quotes) in our example.","type":"text"}]},{"type":"codeBlock","content":[{"text":"keytool -list -v -keystore workbench.p12 -storetype PKCS12\nEnter keystore password: ********","type":"text"}]},{"type":"paragraph","content":[{"text":"If you need to export your certificate for signing you can use a command like the following:","type":"text"}]},{"type":"codeBlock","content":[{"text":"keytool -certreq -keyalg RSA -alias workbench -keystore workbench.p12\n-storepass changeit -sigalg SHA256withRSA -file C:\\dm\\mci\\workbench.csr ","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that with the exception of ","type":"text"},{"text":"keytool -list","type":"text","marks":[{"type":"code"}]},{"text":" the ","type":"text"},{"text":"keytool","type":"text","marks":[{"type":"code"}]},{"text":" command will not normally return a value to the console to indicate it has executed successfully","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Regenerating keys","type":"text"}]},{"type":"paragraph","content":[{"text":"If you want to regenerate your keystore certificate for any reason (i.e. it has expired) you can use the following command: ","type":"text"}]},{"type":"codeBlock","content":[{"text":"# Delete it\n$> keytool -delete -noprompt -alias workbench -keystore workbench.p12 -storepass changeit\n\n# Verify it has been deleted \n$> keytool -list -v -keystore /opt/dm/mci/workbench.p12 -storetype PKCS12 -storepass changeit\nKeystore type: PKCS12\nKeystore provider: SunJSSE\n\nYour keystore contains 0 entries\n$>","type":"text"}]},{"type":"rule"},{"type":"heading","attrs":{"level":1},"content":[{"text":"Enabling HTTPS support in the MettleCI Workbench ","type":"text"},{"text":"config.yml","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"Once a keystore containing the Workbench HTTPS certificate has been created, update your MettleCI ","type":"text"},{"text":"config.yml","type":"text","marks":[{"type":"code"}]},{"text":" file to add the following section: ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"server:\n applicationConnectors:\n - type: https\n port: 8443\n keyStoreType: PKCS12\n keyStorePath: \n keyStorePassword: \n trustStoreType: PKCS12\n trustStorePath: \n trustStorePassword: ","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" must match those used while creating the Java keystore. For example:","type":"text"}]},{"type":"expand","attrs":{"title":"Windows"},"content":[{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"server:\n applicationConnectors:\n - type: https\n port: 8443\n keyStoreType: PKCS12\n keyStorePath: C:\\dm\\mci\\workbench.p12\n keyStorePassword: changeit\n trustStoreType: PKCS12\n trustStorePath: C:\\dm\\mci\\workbench.p12\n trustStorePassword: changeit","type":"text"}]},{"type":"paragraph","content":[{"text":"If you wish to allow Workbench to communicate over both HTTP and HTTPS protocols then you configure your ","type":"text"},{"text":"config.yml","type":"text","marks":[{"type":"code"}]},{"text":" like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"server:\n applicationConnectors:\n - type: http\n port: 8080\n - type: https\n port: 8443\n keyStoreType: PKCS12\n keyStorePath: C:\\dm\\mci\\workbench.p12\n keyStorePassword: changeit\n trustStoreType: PKCS12\n trustStorePath: C:\\dm\\mci\\workbench.p12\n trustStorePassword: changeit","type":"text"}]}]},{"type":"expand","attrs":{"title":"Unix"},"content":[{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"server:\n applicationConnectors:\n - type: https\n port: 8443\n keyStoreType: PKCS12\n keyStorePath: /opt/dm/mci/workbench.p12\n keyStorePassword: changeit\n trustStoreType: PKCS12\n trustStorePath: /opt/dm/mci/workbench.p12\n trustStorePassword: changeit","type":"text"}]},{"type":"paragraph","content":[{"text":"If you wish to allow Workbench to communicate over both HTTP and HTTPS protocols then you configure your ","type":"text"},{"text":"config.yml","type":"text","marks":[{"type":"code"}]},{"text":" like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"yaml"},"content":[{"text":"server:\n applicationConnectors:\n - type: http\n port: 8080\n - type: https\n port: 8443\n keyStoreType: PKCS12\n keyStorePath: /opt/dm/mci/workbench.p12\n keyStorePassword: changeit\n trustStoreType: PKCS12\n trustStorePath: /opt/dm/mci/workbench.p12\n trustStorePassword: changeit","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Ensure you use fully qualified references for your KeyStorePath and TrustStorePath as relative references will not work.","type":"text"}]},{"type":"paragraph","content":[{"text":"For example, instead of ","type":"text"},{"text":"./workbench.p12","type":"text","marks":[{"type":"code"}]},{"text":" use ","type":"text"},{"text":"/opt/dm/mci/workbench.p12","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"paragraph","content":[{"text":"The ports given above are only examples, and you’re free to ","type":"text"},{"text":"use custom port numbers","type":"text","marks":[{"type":"link","attrs":{"href":"https://datamigrators.atlassian.net/wiki/spaces/MCIDOC/pages/588972035/Configuring+Workbench+to+use+a+custom+port+number"}}]},{"text":" as desired. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Once your changes are saved restart your Workbench service using the Services utility ","type":"text"},{"type":"status","attrs":{"color":"blue","style":"bold","text":"WIndows","localId":"97c88d4d-a80f-4ad1-8750-4d25f67271f8"}},{"text":" or the commands below for ","type":"text"},{"type":"status","attrs":{"color":"neutral","style":"bold","text":"Unix","localId":"881e9bcf-285a-49b2-a2f5-6ac147de4d27"}},{"text":".","type":"text"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"text":"sudo service dm-mettleci-workbench stop\nsudo service dm-mettleci-workbench start","type":"text"}]},{"type":"paragraph","content":[{"text":"Verify Workbench is up and running under HTTP and/or HTTPS by navigating to ","type":"text"},{"text":"https://:8443","type":"text","marks":[{"type":"code"}]},{"text":" and/or ","type":"text"},{"text":"http://:8080","type":"text","marks":[{"type":"code"}]},{"text":" (as appropriate) in your browser.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Trusting your certificate","type":"text"}]},{"type":"paragraph","content":[{"text":"You will need your local browser to trust the certificate on your DataStage engine tier. There will be slightly different processes for this depending upon your chosen browser and whether or not you have self-signed the certificate or used a CA.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Inspecting your certificate","type":"text"}]},{"type":"paragraph","content":[{"text":"Typically, when you first connect to Workbench using HTTPS you will see a certificate error in your browser. This may look like this…","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":50.0},"content":[{"type":"media","attrs":{"width":692,"id":"844e8e07-7ba5-49be-bcb8-cd6bf19e67b5","collection":"contentId-458556297","type":"file","height":79}}]},{"type":"paragraph","content":[{"text":"or this…","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":50.0},"content":[{"type":"media","attrs":{"width":468,"id":"75b8abe9-cee2-4ea9-8ca4-2a72aa892aa3","collection":"contentId-458556297","type":"file","height":60}}]},{"type":"paragraph","content":[{"text":"Click on the warning indicator ('Not secure' or ‘Certificate error’ in these examples) and select ","type":"text"},{"text":"Certificate (not valid)","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":30.0},"content":[{"type":"media","attrs":{"width":651,"id":"6db6161c-a295-49a0-b5bd-4dab7b02030d","collection":"contentId-458556297","type":"file","height":1002}}]},{"type":"paragraph","content":[{"text":"This will present a certificate dialog which may or may not allow you to install the certificate.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before you install your certificate click on the ","type":"text"},{"text":"Details","type":"text","marks":[{"type":"strong"}]},{"text":" tab and look at the ","type":"text"},{"text":"Thumbprint algorithm","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"Thumbprint","type":"text","marks":[{"type":"strong"}]},{"text":" values. ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":30.0},"content":[{"type":"media","attrs":{"width":453,"id":"cc0567fd-36ac-46ca-9e0c-339154899f94","collection":"contentId-458556297","type":"file","height":548}}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Thumbprint","type":"text","marks":[{"type":"strong"}]},{"text":" value should match the appropriate value displayed by the ","type":"text"},{"text":"keytool -list","type":"text","marks":[{"type":"code"}]},{"text":" command you entered when you first generated your certificate keystore.","type":"text"}]},{"type":"codeBlock","content":[{"text":"Certificate fingerprints:\n MD5: 86:6A:96:1E:29:19:45:F9:46:B9:E6:54:DD:D0:1D:6C\n SHA1: 11:A1:75:E2:71:AA:5D:C8:85:8A:BF:65:02:FC:09:2D:C7:41:CA:BC\n SHA256: 5C:3A:87:77:13:17:77:F8:7C:2F:8A:F4:48:0D:B6:61:31:92:91:B6:90:36:0B:4C:5B:BC:30:5F:EC:C1:CA:36","type":"text"}]},{"type":"paragraph","content":[{"text":"Once you’re happy that the thumbprint matches you can proceed to installing your certificate. ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Installing your certificate","type":"text"}]},{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"Install Certificate","type":"text","marks":[{"type":"strong"}]},{"text":" is enabled then click it to install the certificate into the ","type":"text"},{"text":"Trust Root Certification Authorities","type":"text","marks":[{"type":"em"}]},{"text":" store","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":30.0},"content":[{"type":"media","attrs":{"width":454,"id":"817f4572-000e-4c3d-8087-e806bed3c45f","collection":"contentId-458556297","type":"file","height":554}}]},{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"Install Certificate","type":"text","marks":[{"type":"strong"}]},{"text":" is not enabled then select the ","type":"text"},{"text":"Details","type":"text","marks":[{"type":"strong"}]},{"text":" tab in the Certificate dialog then click ","type":"text"},{"text":"Copy to File","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center","width":30.0},"content":[{"type":"media","attrs":{"width":814,"id":"8ca87633-e8f1-4265-83a3-fb5221b7ccd1","collection":"contentId-458556297","type":"file","height":1024}}]},{"type":"paragraph"},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Start the Certificate Export Wizard by clicking ","type":"text"},{"text":"Next","type":"text","marks":[{"type":"strong"}]},{"text":", accept the default settings, enter a meaningful certificate name to export it to your local system, and click ","type":"text"},{"text":"Finish","type":"text","marks":[{"type":"strong"}]},{"text":". Now the certificate has been successfully exported to a file.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In the Certificate Export Wizard success message, click ","type":"text"},{"text":"Finish","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In the Certificate dialog, click ","type":"text"},{"text":"OK","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"You can now follow your operating system’s process for importing the certificate file into the ","type":"text"},{"text":"Trust Root Certification Authorities","type":"text","marks":[{"type":"em"}]},{"text":" store.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":" Ensure you restart your browser after installing your certificate!","type":"text"}]}]}],"version":1}