Server Security Support - ni/grpc-device GitHub Wiki
grpc-device
allows clients direct access to NI driver APIs. This allows the client to control connected hardware and, in some cases,
allows unsafe operations and access to the underlying system. Always ensure that your grpc-device
server is secure.
The gRPC server supports both server-side TLS and mutual TLS. Security configuration is accomplished by setting the server_cert
, server_key
and root_cert
values in the server's configuration file. The server expects the certificate files specified in the configuration file to exist in a certs
folder that is located in the same directory as the configuration file being used by the server.
In the default case the server expects the certs
folder to be located in the same folder as the server executable itself:
server_installation_folder/
├── certs/
│ ├── client_self_signed_crt.pem
│ ├── server_privatekey.pem
│ └── server_self_signed_crt.pem
├── ni_grpc_device_server
└── server_config.json
If a path to the configuration file is specified when starting the server then the certs
folder must be located in the same location as the specified configuration file:
server_installation_folder/
└── ni_grpc_device_server
config_file_folder/
├── certs/
│ ├── client_self_signed_crt.pem
│ ├── server_privatekey.pem
│ └── server_self_signed_crt.pem
└── mutual_tls.json
- When none of the security-related configuration values are set then the server defaults to an insecure (no SSL/TLS) configuration. Additionally, if one of the
server_cert
orserver_key
values is set but not the other then the server will also default to an insecure configuration. Specifying one of the two is considered an incomplete configuration. - To configure the server for server-side TLS then set both the
server_cert
andserver_key
values. In this configuration only the identity of the server is verified:
{
"port": 31763,
"security" : {
"server_cert": "server_self_signed_crt.pem",
"server_key": "server_privatekey.pem",
"root_cert": ""
}
}
- To configure the server for mutual TLS then set the
server_cert
,server_key
androot_cert
values. This configuration verifies the identity of the client in addition to the identity of the server. When theroot_cert
is specified the server always requests a client certificate:
{
"port": 31763,
"security" : {
"server_cert": "server_self_signed_crt.pem",
"server_key": "server_privatekey.pem",
"root_cert": "client_self_signed_crt.pem"
}
}
Note: The server's configuration (insecure, server-side TLS or mutual TLS) will always be printed to the terminal when the server starts.
A detailed explanation of security considerations is outside of the scope of this document. To read more about SSL/TLS in gRPC refer to this document.
There are many tools available to produce certificate files for SSL/TLS. One such tool is openssl
and below is a simple example that creates self-signed server and client certificates:
openssl genrsa -passout pass:1111 -des3 -out ca.key 2048
openssl req -passin pass:1111 -new -x509 -days 3650 -key ca.key -out ca.crt -subj "/C=US/ST=Texas/L=Austin/O=NI/OU=R&D/CN=MachineName"
openssl genrsa -passout pass:1111 -des3 -out server_privatekey.pem 2048
openssl req -passin pass:1111 -new -key server_privatekey.pem -out server_csr.pem -subj "/C=US/ST=Texas/L=Austin/O=NI/OU=R&D/CN=MachineName"
openssl x509 -req -passin pass:1111 -days 3650 -in server_csr.pem -CA ca.crt -CAkey ca.key -CAcreateserial -out server_self_signed_crt.pem
openssl rsa -passin pass:1111 -in server_privatekey.pem -out server_privatekey.pem
openssl genrsa -passout pass:1111 -des3 -out client_privatekey.pem 2048
openssl req -passin pass:1111 -new -key client_privatekey.pem -out client_csr.pem -subj "/C=US/ST=Texas/L=Austin/O=NI/OU=R&D/CN=MachineName"
openssl x509 -passin pass:1111 -req -days 3650 -in client_csr.pem -CA ca.crt -CAkey ca.key -CAcreateserial -out client_self_signed_crt.pem
openssl rsa -passin pass:1111 -in client_privatekey.pem -out client_privatekey.pem
The examples in this section make use of the certificates generated in the Creating Certificates section. Your specific configuration (i.e. the certificate files you use) will be dependent on how you generate the certificate files.
- To establish a connection to an insecure server then call the
insecure_channel(..)
method:
channel = grpc.insecure_channel(serverAddress)
- To establish a connection to a server configured for server-side TLS then call the
secure_channel(..)
method and setroot_certificates
to point to the server's self-signed certificate:
root_cert = open('server_self_signed_crt.pem', 'rb').read()
creds = grpc.ssl_channel_credentials(root_certificates=root_cert)
channel = grpc.secure_channel(serverAddress, creds)
-
To establish a connection to a server configured for mutual TLS then call the
secure_channel(..)
method and set:-
root_certificates
to point to the server's self-signed certificate -
certificate_chain
to point to the client's self-signed certificate -
private_key
to point to the client's private key
-
root_cert = open('server_self_signed_crt.pem', 'rb').read()
client_cert = open('client_self_signed_crt.pem', 'rb').read()
client_key = open('client_privatekey.pem', 'rb').read()
creds = grpc.ssl_channel_credentials(root_certificates=root_cert , private_key=client_key, certificate_chain=client_cert)
channel = grpc.secure_channel(serverAddress, creds)
Note: When using the grpclib.client
API with supporting files generated using betterproto
the security configuration on the client side is different than the examples above. The grpclib.client
API uses SSLContext
from the Python ssl
module. Below is an example configured for mutual TLS:
ctx = ssl.SSLContext(ssl.PROTOCOL_TLS)
ctx.verify_mode = ssl.CERT_REQUIRED
ctx.load_cert_chain("client_self_signed_crt.pem", "client_privatekey.pem")
ctx.load_verify_locations("server_self_signed_crt.pem")
ctx.set_alpn_protocols(['h2'])
channel = Channel(host="localhost", port=31763, ssl=ctx)
- If the server can't find the certificate file at the expected location then the server will fail to start and an error message will be printed to the terminal. In this case verify that the certificate file exists at the correct location and that the user has read permissions for the file.
- If a client fails to connect to the server the cause can be one of many reasons. To determine if the failure is related to the security configuration review the server's terminal output. SSL/TLS error messages will be printed to the terminal where the server is running. Below is an example error message on the server side when the server expects a client certificate but does not receive it:
E0301 12:10:55.011000000 1136 ssl_transport_security.cc:1455] Handshake failed with fatal error SSL_ERROR_SSL: error:100000c0:SSL routines:OPENSSL_internal:PEER_DID_NOT_RETURN_A_CERTIFICATE.
- One common error state occurs when a client creates a channel for a configuration different from the server. For example, the server might be configured for mutual TLS and the client configures an insecure channel (no security) or server-side TLS (no client certificate specified). In this case the client will typically see an
UNAVAILABLE
error status on the first RPC call. The gRPC connection utilizes lazy intialization and therefore the connection isn't established until the first RPC called is made. Below is an example call stack from a Python client:
<class 'grpc._channel._InactiveRpcError'>
Traceback (most recent call last):
File "C:\Users\username\Desktop\Demo\client.py", line 22, in <module>
response = server.IsReservedByClient(serverTypes.IsReservedByClientRequest(reservation_id=reservation_id, client_id=client_id))
File "C:\Users\username\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\grpc\_channel.py", line 923, in __call__
return _end_unary_response_blocking(state, call, False, None)
File "C:\Users\username\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages\grpc\_channel.py", line 826, in _end_unary_response_blocking
raise _InactiveRpcError(state)
grpc._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with:
status = StatusCode.UNAVAILABLE
details = "failed to connect to all addresses"
debug_error_string = "{"created":"@1614621623.440000000","description":"Failed to pick subchannel","file":"src/core/ext/filters/client_channel/client_channel.cc","file_line":5391,"referenced_errors":[{"created":"@1614621623.440000000","description":"failed to connect to all addresses","file":"src/core/ext/filters/client_channel/lb_policy/pick_first/pick_first.cc","file_line":398,"grpc_status":14}]}"