Differences

This shows you the differences between two versions of the page.

--- websocketsdocumentation [2022/08/31 00:10] – wikiadmin
+++ websocketsdocumentation [2023/10/08 13:41] (current) – wikiadmin
@@ Line 25: / Line 25: @@
 To test this insecure connection, put MIStudio into LIVE mode and use the MIStudio Test Frame to enter a value into the text field. It will appear in the client's annunciator.
-The steps to use the WebSocket server and client with a secure connection is describe in the next sections.
+The steps to use the WebSocket server and client with a secure connection is described in the next sections, starting with making a certificate for the server.
 ==== Self-Signed Certificate Generation ====
@@ Line 31: / Line 31: @@
 To run the server with self-signed certificates you need to generate a public and private certificate for the server and the public certificate must be moved to the client.
-To generate server certificates run:
+<note important>Use OpenSSL version 1.1.1q and not OpenSSL 3.</note>
-//openssl req -newkey rsa:2048 -x509 -keyout key.pem -out cert.pem -days 365//
+OpenSSL is usually installed by default on Linux systems. For Windows you can get OpenSSL 1.1.1q from https://slproweb.com/products/Win32OpenSSL.html
-The tool will prompt us to enter a PEM passphrase and other information.  You can choose a passphrase, but need to save it for use below.
+To generate the private (key.pem) and public (cert.pem) certificates run:
-When prompted for the "Common Name" add the name of the server.  eg for the default
-URI wss:%%//%%localhost:8887 add:
-//Common Name (e.g. server FQDN or YOUR name) []:localhost//
+<code Windows>
+openssl req -newkey rsa:2048 -x509 -keyout key.pem -out cert.pem -days 365
+</code>
+OpenSSL will prompt you for several values. You can enter a dot (".") for no answer to the questions, or enter the values when prompted.
+Passphrase: he tool will prompt us to enter a PEM passphrase and other information.  Choose a passphrase of 4 or more characters, but remember what this passphrase is because you'll need to use this in the next OpenSSL generator step.
+To generate a private key without encrypting  with a passphrase use the -nodes (short for "no DES") option
+<code Windows>
+openssl req -newkey rsa:2048 -nodes -x509 -keyout key.pem -out cert.pem -days 365
+</code>
+Common Name: When prompted for the "Common Name" add the name of the server. If you are testing on "localhost", as when you test in MIStudio or MIX, answer with "localhost". If you plan to test on two networked systems, enter the web address of where the server will be running (do not enter the wss part, only the web server address, such as www.domainname.com).
+<code Windows>
+Common Name (e.g. server FQDN or YOUR name) []:localhost
+</code>
 Once we've answered all the prompts, the openssl tool outputs two files:
@@ Line 50: / Line 64: @@
 Some additional details are provided at:[[https://www.baeldung.com/convert-pem-to-jks|Converting a PEM File to Java KeyStore Format]] which was the source of this information.
-The server requires that the certificate be in PKCS12 format:
+The server requires that the certificate be in PKCS12 format. So we need to convert the cert.pem generated in the step above to cert.p12 (a certificate in PKCS12 format).
-To convert PEM into a PKCS12 format:
-openssl pkcs12 -export -in cert.pem -inkey key.pem -out certificate.p12 -name "certificate"
+To convert the server certificate PEM into a PKCS12 format, and assigning "mix123" as the new certificate's password:
-While the command runs, we'll be prompted to enter the passphrase that we created previously for key.pem:
+<code Windows>
-Enter pass phrase for key.pem:    [This is the passphrase you entered above]
+openssl pkcs12 -export -in cert.pem -inkey key.pem -out cert.p12 -passout pass:mix123
-And then we'll see the prompt asking for a new password for certificate.p12:
+</code>
-Enter Export Password:  [This can be the same as the passphrase or different.  This is used in the server "CertPassword" property.
-After that, we'll have a certificate.p12 KeyStore stored in PCKS12 format.  Copy certificate.p12 and cert.pem into the UserFiles folder of the MIStudio project.
+While the command runs, you'll be prompted to enter the passphrase that we created previously for key.pem. Enter pass phrase for key.pem (this is the passphrase you entered above). The command line above assigns the password "mix123" to the new cert.p12 certificate. You can use the same passphrase as you entered above, or a different one for the new certificate.
-Set the "P12Certificate" property to be "certificate.p12" and the Cert Password to be the password entered above.  Set the "TrustedCert" property in the client to be "cert.pem" (or copy the certificate to a different web socket client following the instructions for that client).
+After that, you'll have a cert.p12 KeyStore stored in PCKS12 format.
+Copy cert.p12 and cert.pem into the UserFiles folder of the MIStudio project.
+Set the "P12Certificate" property to be "cert.p12" and the Cert Password to be the password entered above (mix123 for this example).  Set the "TrustedCert" property in the client to be "cert.pem" (or copy the certificate to a different web socket client following the instructions for that client).
@@ Line 78: / Line 94: @@
 Server URI:(ServerUri)This URI of the server, eg wss:%%//%%yourhost:port
-Trusted Certificate:(TrustedCert)The trusted server certificate in PEM format
+<wrap hi>Be sure to use wss:%%//%% for a secure connection (with certificates) and ws:%%//%% for an insecure (no certificates) connection</wrap>
+Trusted Certificate:(TrustedCert)The trusted server certificate in PEM format. Only needed for a secure connection.
 ==== Examples of Use ====