This section describes how to use the KMC encryption algorithm to generate the CA key and KMC key file. The following uses certImport.sh as an example to describe how to use CertImport (a C++ executable program) in the ${MX_SDK_HOME}/bin directory to verify and import a certificate, and generate and write a key.
- Before executing the script, ensure that the current user who executes the script and the owner of the files to be imported are the user who installs Vision SDK. If the keys folder exists in the current directory, ensure that the permission on the folder is 700 and the owner is the user who executes the script. If the keys folder contains the ca.crt, server.crt, server.key, and ca.crl (optional) files, back up and then delete the files based on service requirements before executing the script. If the keys folder does not exist, ignore this note.
- Ensure that the owner of the imported certificate, private key, and CRL files is the user who executes the script. The permission on the imported private key file cannot be greater than 640. You are advised to set the permission on the files to be imported to 400 before importing them.
- This script contains multiple steps, such as certificate copy and key encryption. If the key encryption fails, files such as certificates have been copied. By default, the copied files cannot be written. To execute the script again, delete the copied files in the target path first.
- The import script supports only RSA key import. The certificate signature algorithm can only be sha256 or sha512.
- Run the following command to view the help information about certImport.sh:
1$ bash ./certImport.sh -h
- Do not use different accounts when running KMC scripts. Otherwise, the function of recording the operation user in logs may be affected.
- The certImport.sh script is called in the StreamServer startup script (run.sh). You do not need to use this script separately.
- Go to the $MX_SDK_HOME/sample/mxVision/streamserver/ directory which contains the following content:
1 2 3 4 5
├── InferConfigRepository │ ├── ... ├── run.sh // StreamServer startup script ├── certImport.sh // Script for importing and encrypting the certificate ├── ...
- Run the script to import the certificate and generate the KMC ciphertext key.
Execute KMC-related encryption algorithms, including certificate verification, KMC encryption, and configuration file writing. The following is a command example.
$ bash ./certImport.sh -c <ca.crt_path> -s <server.crt_path> -k <server.key_path>
<ca.crt_path> indicates the path of the CA certificate, <server.crt_path> indicates the path of the server certificate, and <server.key_path> indicates the path of the server certificate key. These parameters are input by adding -c, -s, and -k, respectively.
This script is used to import certificate and key files. During the script execution, you need to enter the password of the server certificate. The password can contain a maximum of 100 characters.
- If the certificate is successfully verified and encrypted, the certificate in the specified path is copied to the keys folder in the current directory, and the relative paths are written to ca_crt, server_crt, and server_key in the $MX_SDK_HOME/config/streamserver.conf file.
- If the master key file kmc.ks and backup key file StandbyKsf.ks do not exist in the current directory, kmc.ks and StandbyKsf.ks are generated in the keys folder of the current directory during encryption. The generated key information is automatically filled in server_key_mm in $MX_SDK_HOME/config/streamserver.conf.
The command output is as follows:
$ bash ./certImport.sh -c <ca.crt_path> -s <server.crt_path> -k <server.key_path> -r <crl_path>
<ca.crt_path> indicates the CA certificate path, <server.crt_path> indicates the server certificate path, <server.key_path> indicates the server certificate key path, and <crl_path> indicates the CRL path. Input them by adding -c, -s, -k, and -r, respectively.
This script is used to import certificates, keys, and CRLs. During the script execution, you need to enter the server certificate password which cannot exceed 100 characters.
- If the certificate is successfully verified and encrypted, the certificate, key, and CRL in the specified path are copied to the keys folder in the current directory, and the relative paths are written to ca_crt, server_crt, server_key and crl in the $MX_SDK_HOME/config/streamserver.conf file.
- If the master key file kmc.ks and backup key file StandbyKsf.ks do not exist in the current directory, kmc.ks and StandbyKsf.ks are generated in the keys folder of the current directory during encryption. The generated key information is automatically filled in server_key_mm in $MX_SDK_HOME/config/streamserver.conf.
- If the system displays a message indicating that the import fails because the CRL is invalid or the CRL is not used temporarily, check crl in the streamserver.conf file. If this parameter is not empty, manually leave it empty.
- If a CRL is specified in the configuration file when the service is started, you can update the file in the CRL path when the service is running to dynamically revoke the client certificate. The CRL file cannot be directly overwritten. You need to delete it and copy the new CRL file with the same name to the corresponding path. (Ensure that the owner of the new CRL file is the same as the Vision SDK installation user and the owner's permission is 400.) If no CRL is specified during startup, the CRL cannot be modified when the service is running.
- When the KMC is used for encrypted calculation, the KMC initialization random number might be blocked but no error is reported. The problem can be resolved after waiting for some time. For details, see Installing Dependencies to install haveged.
- The script execution file is stored in $MX_SDK_HOME/bin/CertImport.
- If the import script fails to be executed, the information in the configuration file may not change. In this case, you need to manually set the configuration items in the configuration file.
- After the script is executed successfully, the directory structure is generated. You can start the service as required.
1 2 3 4 5 6 7 8 9 10 11 12
├── InferConfigRepository │ ├── ... ├── keys │ ├── ca.crt // CA certificate │ ├── server.crt // Server certificate │ ├── server.key // Server key │ ├── ca.crl // CA CRL (optional) │ ├── kmc.ks // KMC master key │ ├── StandbyKsf.ks // KMC backup key ├── run.sh // StreamServer startup script ├── certImport.sh // Script for importing and encrypting the certificate ├── ...
Updating and Replacing the Certificate, Private Key, and CRL
During service running, if the certificate, private key, or CRL needs to be updated or replaced due to such reasons as certificate expiration, the owner of the current certificate and other files needs to perform the following steps in sequence:
- Back up the keys folder or the certificate, private key, or CRL files to be replaced in the keys folder.
- Delete the certificate, private key, or CRL files to be replaced from the keys folder.
- Import the certificate, private key, or CRL using either of the following methods:
- Run the cp command to copy the new certificate, private key, or CRL files in the same format as the original ones to the keys folder. The name and owner of the new files must be the same as those of the files to be replaced. The owner of those files must be the user who installs Vision SDK, and the permission on those new files must be set to 400.
- Run the certImport.sh script to import the new certificate, private key, and CRL. If you use an import script, back up the files to be replaced of the parameters specified in the script. After the importing succeeds, server_key_mm in the configuration file may be updated.
During the update and replacement, requests sent to the inference service may be abnormal due to the lack of related certificate, private key, or CRL files.
After the update is complete, delete the replaced certificate, private key, and CRL files in a timely manner to prevent information leakage.