Update the APIs used in the transport secure documentation #785
Conversation
| `2020.3 (2020.3.34 minimum and above), 2021.3 (2021.3.1f1 minimum and above) and 2022.1 (2022.1.0b16 minimum and above)` | ||
| The Unity Transport package can be configure to encrypt the connection between the server and the client while ensuring the server's/client's authenticity. | ||
|
|
||
| Secure connections are available with editor versions 2020.3 (starting at 2020.3.34), 2021.3, and 2022.1 and above. | ||
|
|
There was a problem hiding this comment.
You can configure the Unity Transport package to encrypt the server-client connection while ensuring the authenticity of both the server and the client.
Secure connections are available with Editor versions 2020.3 (starting at 2020.3.34), 2021.3, and 2022.1 and above.
|
|
||
| ## Server authentication | ||
|
|
||
| :::warning Warning | ||
| Be sure private keys are not included in your code base or client builds. | ||
| This example uses hardcoded certificates to make understanding the process easier, but in a real deployment the server certificates should be kept separate from client builds. One way to achieve this is to put them on a separate assembly, or load them from a file on the server. | ||
| ::: |
There was a problem hiding this comment.
This example uses hardcoded certificates to illustrate the process better. However, in an actual deployment, you should keep the server certificates separate from the client builds. You can do this by keeping the server certificates on a separate assembly or by loading the server certificates from a file on the server.
| In this configuration, the server will provide a certificate to the client (`certificate`) containing the server host name. | ||
| The client will compare the server hostname to the one it knows (`serverName`) and will then validate the provided certificate against its own root certificate (`caCertificate`) confirming the server identity. | ||
|
|
||
| In this configuration, the server will provide a certificate to the client (`certificate`) to prove its identity. The client will validate the certificate against its own root certificate (`caCertificate`) to validate its identity. | ||
|
|
There was a problem hiding this comment.
In this configuration, the server provides a certificate to the client (
certificate) to prove its identity. The client validates the certificate against its own root certificate (caCertificate) to validate its identity.
I'm not sure this reads correctly. In the second sentence, it's unclear whether the client is using the certificate to validate its own or the server's identity.
Maybe this is more correct?
In this configuration, the server provides a certificate to the client (
certificate) to prove its identity. The client uses its own root certificate (caCertificate) to validate the certificate from the server.
There was a problem hiding this comment.
Yes, your suggestion is correct and much clearer. Thanks!
| ::: | ||
|
|
||
| Once its identity confirmed, the server will then use the private key (`privateKey`) to establish the secure communication. | ||
| Once its identity confirmed, the server will then use the private key (`privateKey`) to establish the secure communication channel. | ||
|
|
There was a problem hiding this comment.
After confirming its identity, the server uses the private key (
privateKey) to establish a secure communication channel.
| To use the client server secure workflow, you need a `valid certificate` and the `root certificate` it has been generated from. You also need the `private key` that has been used to create the certificate. | ||
| If you don't have these, they can be generated using OpenSSL. The procedure is detailed hereafter. | ||
|
|
||
| To use the client/server secure workflow, you need a valid certificate and the root certificate that was used to sign it. You also need the private key that has been used to create the certificate. If you don't have these, they can be generated using OpenSSL. The procedure is detailed hereafter. | ||
|
|
There was a problem hiding this comment.
You need the following before you can use the client-server secure workflow:
- A valid certificate
- The root certificate used to sign the certificate
- The private key used to create the certificate
You can use OpenSSL to generate these if you don't have them. The procedure is detailed hereafter.
|
|
||
| #### Generate the root-signed certificate to use with the server | ||
|
|
||
| Create now a private key for the server. | ||
|
|
There was a problem hiding this comment.
Create a private key for the server.
Or
Now, create a private key for the server.
| From this private key, you can generate a certificate signing request. | ||
|
|
||
| From this private key, you can generate a certificate signing request. | ||
|
|
There was a problem hiding this comment.
You can use this private key to generate a certificate signing request.
| You'll be prompted with the same questions as for generating the root certificate. The answers are no more important, except for the common name: it is recommended to use the server's hostname. | ||
|
|
||
| Finally, using the different files generated, we can create the certificate file the server will use to authenticate itself: | ||
|
|
There was a problem hiding this comment.
You'll be prompted with the same questions you answered when generating the root certificate. The answers are no more important (except for the common name: it is recommended to use the server's hostname).
Finally, you can create the certificate file the server will use to authenticate itself using the generated files:
| ### Boilerplate file holding the secure parameters | ||
|
|
||
| Create a `SecureParameters.cs` script file to hold your certificates and the private key. Place it in the same folder as the minimal server and minimal client scripts. Then declare the `SecureParameters` static class and the boilerplate code that will hold your secure information: | ||
|
|
There was a problem hiding this comment.
You should have now generated a total of five files. You only need to use the following three:
myGameClientCA.pem,myGameServerCertificate.pem, andmyGameServerPrivateKey.pem.
- On the client side, you need the content of the
myGameClientCA.pemfor thecaCertificateparameter.- On the server end, you need the contents of
myGameServerCertificate.pemfor thecertificateparameter.- On the server end, you need the contents of
myGameServerPrivateKey.pemfor theprivateKeyparameter.Boilerplate file holding the secure parameters
Create a
SecureParameters.csscript file to hold your certificates and the private key. Place it in the same folder as the minimal server and minimal client scripts. Then, declare theSecureParametersstatic class and the boilerplate code that will hold your secure information:
|
|
||
| :::note | ||
| If you create clients for multiple platform, it is important for all of these to use the same Root Certificate if they communicate with the same server. | ||
| If you create clients for multiple platforms, it is important for all of these to still use the same root certificate if they communicate with the same server. | ||
| ::: |
There was a problem hiding this comment.
If you create clients for multiple platforms, it is important for all clients to continue using the same root certificate if they communicate with the same server.
I applied all your suggestions. Thanks for the review! |
Select the type of change:
Purpose of the Pull Request:
This PR updates the documentation for secure communications in the transport to use the new simpler APIs provided in UTP 1.3. I've also taken the liberty of making small edits to the documentation to make it easier to understand.
Note that this shouldn't be merged until UTP 1.3 is released.
Issue Number: N/A