Skip to content

CA

Jump to bottom
silencht edited this page Apr 21, 2026 · 2 revisions

遥操作服务：SSL/TLS 证书部署完整指南

Teleoperation Service: A Complete Guide to SSL/TLS Certificate Deployment

适用场景：为 xr_teleoperate（遥操作）与 teleimager（视频流）服务构建私有可信证书体系，使 Pico、Quest、Apple Vision Pro 或 Chrome 浏览器能够通过 HTTPS 安全访问内网服务器。

Use Case: Establish a private trusted certificate infrastructure for the xr_teleoperate (teleoperation) and teleimager (video streaming) services, enabling Pico, Quest, Apple Vision Pro, or Chrome browsers to securely access the intranet server over HTTPS.

核心目标：在客户端与服务器之间建立一条由私有根证书颁发机构（Root CA）担保的加密信任链，消除浏览器证书警告。

Core Objective: Build an encrypted trust chain guaranteed by a private Root Certificate Authority (Root CA) between the client and the server, eliminating browser certificate warnings.

角色说明： 为便于区分操作权限，后文统一使用以下称谓：

  • 管理员：负责生成 CA 密钥材料、签发证书，同时也负责在服务器主机上部署证书与私钥。
  • 服务器：运行遥操作服务的机器（后文以 Unitree G1 机器人中 Jetson NX 设备的 IP 192.168.123.164 为例，请替换为您的实际服务器 IP）。
  • 客户端：Pico、Quest、Apple Vision Pro 头显设备或笔记本电脑，需要信任服务器证书。

Role Definitions: To distinguish operational privileges, the following terms are used throughout this guide:

  • Administrator: Responsible for generating CA key material and issuing certificates, as well as deploying the certificate and private key on the server host.
  • Server: The machine running the teleoperation service (hereinafter exemplified by the IP 192.168.123.164 of the Jetson NX device in the Unitree G1 robot—please replace this with your actual server IP).
  • Client: Pico, Quest, Apple Vision Pro headsets, or laptops that need to trust the server certificate.

注意：由于本场景为自签发证书部署，证书的签发管理员与服务器的运维者为同一人或同一团队。

Note: As this scenario involves self-signed certificate deployment, the administrator issuing the certificate and the operator maintaining the server are the same person or team.

第一步：管理员建立私有根证书颁发机构（Root CA）

Step 1: Administrator Establishes a Private Root Certificate Authority (Root CA)

为什么需要这一步？

SSL/TLS 协议要求客户端必须能够验证服务器证书的签发来源。商业证书由操作系统内置的公共 CA（如 DigiCert）签名，而内网自签证书则需要管理员预先创建一个私有 CA，作为整个内网环境的信任锚点。客户端只有在本地安装此 CA 的根证书后，才会接纳由该 CA 签发的所有服务器证书。

Why This Step Is Necessary

The SSL/TLS protocol requires the client to verify the issuer of the server certificate. Commercial certificates are signed by public CAs built into operating systems (e.g., DigiCert), whereas intranet self-signed certificates require the administrator to first create a private CA to serve as the trust anchor for the entire intranet environment. Only after the client installs this CA's root certificate locally will it accept all server certificates signed by that CA.

管理员执行以下操作

在管理员本地终端（非服务器）执行 openssl 命令，生成 Root CA 的私钥与自签名根证书。

Actions Performed by the Administrator

Execute the following openssl command in the administrator's local terminal (not on the server) to generate the Root CA's private key and self-signed root certificate.

openssl req -x509 -newkey rsa:2048 -nodes \
-keyout unitree_xr_teleoperate_ca.key \
-out unitree_xr_teleoperate_ca.crt \
-days 3650 -subj "/CN=xr_teleoperate"

产出文件与归宿：

Generated Files and Their Destinations:

文件 File 文件类型 File Type 存放位置 Storage Location 安全要求 Security Requirement
unitree_xr_teleoperate_ca.key CA 私钥 CA Private Key 管理员离线存储介质
Administrator's Offline Storage Medium 		必须保密，仅用于签发子证书；泄露即意味着整个信任体系崩塌。
Must remain confidential; used only for issuing subordinate certificates. Leakage compromises the entire trust infrastructure.
unitree_xr_teleoperate_ca.crt 根证书 Root Certificate 管理员暂存，后续分发至客户端进行安装
Staged by administrator, later distributed to clients for installation		 可公开分发，是客户端建立信任的依据。
Can be distributed publicly; serves as the basis for client trust.

完成 CA 的建立后，接下来需要为服务器主机准备其专属的密钥材料，以便向 CA 管理员提交证书申请。

Once the CA is established, the next step is to prepare the server host's exclusive key material in order to submit a certificate request to the CA administrator.

第二步：为服务器主机生成私钥与证书签名请求（CSR）

Step 2: Generate Private Key and Certificate Signing Request (CSR) for the Server Host

为什么需要这一步？

服务器主机必须拥有一对专属的公钥与私钥。这一对密钥是 TLS 加密通信的数学基础：

  • 私钥（key.pem）由服务器严密保管，绝不外传。在 TLS 握手阶段，服务器用它来解密客户端发来的加密信息，以证明自己就是证书的合法持有者。

  • 公钥在生成私钥的同时就已存在（RSA 私钥文件中天然包含公钥参数）。为了让客户端能够获取并信任这个公钥，它需要经历一个“申请与认证”的过程：

管理员首先将公钥连同服务器身份信息（如主机名）一并写入 证书签名请求（CSR）。此时的 CSR 相当于一张贴好了证件照、填好了个人信息的申请表，但还没有 CA 发证机关的盖章。 管理员将 CSR 提交给私有 CA 进行签名。CA 审核无误后，会将 CSR 中的公钥取出，与身份信息一同封装进一份标准的 X.509 服务器证书（cert.pem），并用自己的私钥盖上“数字钢印”。

简而言之：公钥随 CSR 递交申请，最终以被 CA 签名认证的形式出现在服务器证书中，对外公开。

Why This Step Is Necessary

The server host must possess an exclusive key pair consisting of a public key and a private key. This key pair forms the mathematical foundation of TLS encrypted communication:

  • The private key (key.pem) is strictly guarded by the server and never shared. During the TLS handshake, the server uses it to decrypt encrypted information sent by the client, thereby proving it is the legitimate holder of the certificate.

  • The public key exists as soon as the private key is generated (RSA private key files inherently contain public key parameters). For the client to obtain and trust this public key, it must undergo an "application and authentication" process:

The administrator first writes the public key along with the server's identity information (such as hostname) into a Certificate Signing Request (CSR). At this stage, the CSR is analogous to an application form with an attached photo and personal details filled in, but lacking the stamp of the issuing CA authority. The administrator submits the CSR to the private CA for signing. After verifying the information, the CA extracts the public key from the CSR, encapsulates it together with the identity information into a standard X.509 server certificate (cert.pem), and affixes a "digital seal" using its own private key.

In short: The public key is submitted with the CSR and ultimately appears in the server certificate as CA-signed and authenticated content, available for public disclosure.

执行方式

管理员可在服务器主机上直接执行以下命令，也可在本地生成后将私钥安全传输至服务器（后者更安全）。

Execution Method

The administrator can execute the following commands directly on the server host, or generate the material locally and securely transfer the private key to the server (the latter is more secure).

# 生成 2048 位 RSA 私钥（服务器专用）
# Generate a 2048-bit RSA private key (exclusive to the server)
openssl genrsa -out key.pem 2048

# 基于私钥生成证书签名请求（CSR）
# Generate a Certificate Signing Request (CSR) based on the private key
openssl req -new -key key.pem -out server.csr -subj "/CN=localhost"

参数说明：/CN=localhost 仅为基础标识，最终证书的有效性由 SAN（Subject Alternative Name）扩展 中的 IP 地址决定，该内容将在下一步签发时注入。

Parameter Note: /CN=localhost is only a baseline identifier. The final certificate's validity is determined by the IP address(es) specified in the SAN (Subject Alternative Name) extension, which will be injected during the issuance step.

产出文件与归宿：

Generated Files and Their Destinations:

文件 File 文件类型 File Type 存放位置 Storage Location 安全要求 Security Requirement
key.pem 服务器私钥 Server Private Key 服务器主机（服务配置指向的路径）
Server Host (path referenced in service configuration)		 禁止外泄。
Must not be disclosed.
server.csr 证书签名请求 Certificate Signing Request 临时文件，递交 CA 后即可删除
Temporary file; can be deleted after submission to the CA		 无保密要求。
No confidentiality requirement.

服务器密钥材料与申请文件已就绪。此时 CSR 尚未获得签名授权，客户端将无法认可该证书。因此，必须使用 CA 私钥对 CSR 进行签发，并在此过程中绑定服务器的实际 IP 地址。

The server key material and request file are now ready. At this point, the CSR lacks a valid signature, so clients will not trust the resulting certificate. Therefore, the CA private key must be used to sign the CSR, and the server's actual IP address must be bound during this process.

第三步：管理员签发服务器证书并绑定 IP 地址（SAN 扩展）

Step 3: Administrator Issues Server Certificate and Binds IP Address(es) (SAN Extension)

为什么需要这一步？

  • 签名授权：只有经过 CA 私钥签名的证书，才能被预先安装根证书的客户端认可。
  • 地址绑定（关键）：自 Chrome 58 起，浏览器强制要求证书必须通过 SAN（Subject Alternative Name）扩展 明确列出服务器的 IP 地址或域名。若仅依赖 CSR 中的 CN 字段，客户端将报错 ERR_CERT_COMMON_NAME_INVALID 或 SSL_ERROR_BAD_CERT_DOMAIN。

Why This Step Is Necessary

  • Signature Authorization: Only certificates signed by the CA private key will be trusted by clients that have pre-installed the root certificate.
  • Address Binding (Critical): Since Chrome 58, browsers mandate that certificates must explicitly list the server's IP address(es) or domain name(s) via the SAN (Subject Alternative Name) extension. Relying solely on the CN field from the CSR will cause the client to throw ERR_CERT_COMMON_NAME_INVALID or SSL_ERROR_BAD_CERT_DOMAIN.

管理员执行以下操作

  1. 创建 SAN 配置文件 openssl_san.cnf。请务必将 IP.1 修改为您服务器主机的实际局域网 IP。若您希望预留备用 IP（例如计划切换的地址），可依次增加 IP.2、IP.3 等行。以下为单 IP 配置示例： 
    subjectAltName = @alt_names
[alt_names]
IP.1 = 192.168.123.164
    提示：若您不确定服务器 IP，可在服务器主机终端执行 ip addr 或 ifconfig 查看。

Actions Performed by the Administrator

  1. Create the SAN configuration file openssl_san.cnf. Ensure you replace IP.1 with the actual LAN IP address of your server host. If you wish to reserve backup IPs (e.g., for planned address changes), you can add successive lines like IP.2, IP.3, etc. Example for a single IP:

    subjectAltName = @alt_names
[alt_names]
IP.1 = 192.168.123.164

    Tip: If unsure of the server IP, run ip addr or ifconfig on the server host terminal to check.

  2. 签发证书，有效期设为 10 年（3650 天）：

    openssl x509 -req -in server.csr \
-CA unitree_xr_teleoperate_ca.crt \
-CAkey unitree_xr_teleoperate_ca.key \
-CAcreateserial \
-out cert.pem -days 3650 -sha256 \
-extfile openssl_san.cnf

  3. Issue the certificate with a validity period of 10 years (3650 days):

    openssl x509 -req -in server.csr \
-CA unitree_xr_teleoperate_ca.crt \
-CAkey unitree_xr_teleoperate_ca.key \
-CAcreateserial \
-out cert.pem -days 3650 -sha256 \
-extfile openssl_san.cnf

关于 IP 地址范围的补充说明： 如果您希望服务器在切换局域网 IP 后无需重新签发证书，最直接有效的方法是在 openssl_san.cnf 中将所有可能用到的 IP 地址逐个列出。例如，若您的服务器可能在 192.168.123.164、192.168.123.200 以及 192.168.1.100 之间变动，配置文件可写作：

subjectAltName = @alt_names
[alt_names]
IP.1 = 192.168.123.164
IP.2 = 192.168.123.200
IP.3 = 192.168.123.100

这种方式不使用通配符域名，因此规避了通配符证书在某些客户端环境下的兼容性风险，在 Pico 头显和 Chrome 浏览器中均能稳定工作。

Additional Note on IP Address Coverage: If you wish to avoid reissuing the certificate every time the server changes its LAN IP, the most straightforward and effective approach is to individually list all possible IP addresses the server may use within the openssl_san.cnf file. For example, if your server might move among 192.168.123.164, 192.168.123.200, and 192.168.1.100, the configuration file can be written as:

subjectAltName = @alt_names
[alt_names]
IP.1 = 192.168.123.164
IP.2 = 192.168.123.200
IP.3 = 192.168.1.100

This method does not rely on wildcard domain names, thereby avoiding the compatibility risks associated with wildcard certificates in certain client environments. It functions reliably on Pico headsets and Chrome browsers alike. Simply anticipate and populate the IP list prior to issuing the certificate.

产出文件与归宿：

Generated Files and Their Destinations:

文件 File 文件类型 File Type 存放位置 Storage Location 说明 Description
cert.pem 服务器证书 Server Certificate 服务器主机（与 key.pem 同目录）
Server Host (same directory as key.pem)		 包含 CA 签名与 SAN IP 列表，是客户端验证的对象。
Contains the CA signature and SAN IP list; this is what the client validates.

至此，服务器端所需的证书与私钥已全部生成完毕。在将证书部署到服务并分发根证书之前，有必要先了解客户端验证证书的完整逻辑——这有助于理解每一步配置的意义，并在出现问题时快速定位原因。

At this point, all required server-side certificates and private keys have been generated. Before deploying the certificate to the service and distributing the root certificate, it is helpful to understand the complete client-side certificate validation logic—this clarifies the purpose of each configuration step and aids in rapid troubleshooting.

第四步：理解客户端验证流程（连接建立时的三重检查）

Step 4: Understanding the Client Validation Flow (Triple Check During Connection Establishment)

当 Pico 浏览器或 Chrome 尝试访问 https://192.168.123.164（请替换为您的实际服务器 IP）时，客户端会执行以下三次核验，任一失败均会导致连接中断。

When a Pico browser or Chrome attempts to access https://192.168.123.164 (replace with your actual server IP), the client performs the following three checks. Failure of any one check will terminate the connection.

检查项 Check 技术实现 Technical Implementation 失败后果 Consequence of Failure
1. 信任链验证
1. Trust Chain Validation 		客户端用已安装的 unitree_xr_teleoperate_ca.crt 验证 cert.pem 的签名。
The client uses the installed unitree_xr_teleoperate_ca.crt to verify the signature on cert.pem.		 浏览器提示“您的连接不是私密连接”（NET::ERR_CERT_AUTHORITY_INVALID）。
Browser warns "Your connection is not private" (NET::ERR_CERT_AUTHORITY_INVALID).
2. 主机名/IP 匹配验证
2. Hostname/IP Match Validation 		客户端比对当前访问的 IP 是否在 cert.pem 的 SAN 扩展列表中。
The client checks whether the accessed IP is listed in the SAN extension of cert.pem.		 浏览器提示“您访问的网站使用无效的安全证书”（ERR_CERT_COMMON_NAME_INVALID）。
Browser warns "The site uses an invalid security certificate" (ERR_CERT_COMMON_NAME_INVALID).
3. 私钥持有性验证
3. Private Key Possession Verification 		TLS 握手阶段，客户端用证书公钥加密随机数，服务器必须用 key.pem 解密并返回正确信息。
During the TLS handshake, the client encrypts a random number with the certificate's public key; the server must decrypt it with key.pem and return the correct response.		 握手失败，连接立即终止。
Handshake fails, connection terminates immediately.

关键提醒：

  • 若 服务器主机时间 与客户端相差过大（例如时区错误或硬件时钟偏差），证书的有效期检查也会失败。建议在服务器上执行 ntpdate 或 chronyc 同步时间。
  • 若后续服务器 IP 发生变更，必须重新执行第三步（更新 openssl_san.cnf 中的 IP 并重新签发证书），否则客户端将因 SAN 不匹配而拒绝连接。

Key Reminders:

  • If the server host's system time drifts too far from the client's (e.g., due to timezone misconfiguration or hardware clock skew), the certificate validity period check will also fail. It is recommended to synchronize time on the server using ntpdate or chronyc.
  • If the server IP changes later, Step 3 must be repeated (update the IP(s) in openssl_san.cnf and reissue the certificate); otherwise, clients will reject the connection due to SAN mismatch.

第五步：部署总结与文件清单

Step 5: Deployment Summary and File Manifest

文件名称 File Name 操作角色 Operator Role 最终位置 Final Location 用途摘要 Usage Summary
unitree_xr_teleoperate_ca.crt 管理员 → 客户端
Administrator → Client 		Pico 头显 / Chrome 的“受信任根证书颁发机构”存储区
Pico headset / Chrome "Trusted Root Certification Authorities" store		 信任锚点：客户端用其验证服务器证书的来源合法性。
Trust anchor: Used by the client to verify the origin and legitimacy of the server certificate.
unitree_xr_teleoperate_ca.key 管理员
Administrator 		离线安全介质（加密 U 盘、硬件安全模块）
Offline secure medium (encrypted USB drive, Hardware Security Module)		 签发权力凭证：严禁出现在服务器或客户端。
Signing authority credential: Strictly prohibited from residing on the server or client.
cert.pem 管理员 → 服务器
Administrator → Server 		遥操作服务配置目录（如 /etc/ssl/certs/）
Teleoperation service configuration directory (e.g., /etc/ssl/certs/)		 服务器向客户端出示的身份证明。
Identity proof presented by the server to the client.
key.pem 管理员 → 服务器
Administrator → Server 		遥操作服务配置目录（如 /etc/ssl/private/）
Teleoperation service configuration directory (e.g., /etc/ssl/private/)		 服务器用于解密 TLS 握手的私密钥匙。
Private key used by the server to decrypt the TLS handshake.

管理员后续操作提醒：

  1. 分发根证书：将 unitree_xr_teleoperate_ca.crt 传输至客户端设备并安装（Android/Pico 通过“加密与凭据”->“从存储设备安装证书”；Windows 通过“管理计算机证书”导入“受信任的根证书颁发机构”）。
  2. 配置服务：修改 xr_teleoperate 与 teleimager 的配置文件，分别指定 cert.pem 与 key.pem 的绝对路径，并重启服务。
  3. 验证部署：在客户端浏览器地址栏输入 https://<服务器实际IP>，确认挂锁图标正常显示且无任何证书警告。

Post-Deployment Reminders for the Administrator:

  1. Distribute Root Certificate: Transfer unitree_xr_teleoperate_ca.crt to client devices and install it (Android/Pico: via "Encryption & credentials" -> "Install certificate from storage"; Windows: via "Manage computer certificates" import into "Trusted Root Certification Authorities").
  2. Configure Services: Modify the configuration files of xr_teleoperate and teleimager to point to the absolute paths of cert.pem and key.pem, then restart the services.
  3. Verify Deployment: Enter https://<server_actual_ip> in the client browser's address bar and confirm that the padlock icon appears normally without any certificate warnings.

您说得对，我需要将 PICO 证书安装部分作为前面完整教程的延续章节，而非独立的 4.2.1 节。同时应去除“随附文档中 CA证书 文件夹”这类与前述教程不一致的表述——在前述教程中，unitree_xr_teleoperate_ca.crt 是由管理员在第一步生成并暂存于本地的，不存在预设的文件夹。

以下是衔接前述教程的第六步，采用与前面一致的章节编号格式和中英双语对照。

第六步：在 PICO 设备上安装根证书

Step 6: Installing the Root Certificate on PICO Devices

前述步骤中，管理员已在本地生成了根证书 unitree_xr_teleoperate_ca.crt。为让 PICO 头显信任由该 CA 签发的服务器证书，必须将此根证书安装到 PICO 设备的系统受信任凭据列表中。以下操作假设管理员使用 Ubuntu 22.04 系统的笔记本电脑，通过 USB 连接 PICO4 Ultra Enterprise 设备。

In the previous steps, the administrator generated the root certificate unitree_xr_teleoperate_ca.crt locally. To make the PICO headset trust server certificates issued by this CA, this root certificate must be installed into the device's system trusted credentials list. The following procedure assumes the administrator uses a laptop running Ubuntu 22.04, connected to the PICO4 Ultra Enterprise device via USB.

6.1 传输根证书至 PICO 设备

6.1 Transfer the Root Certificate to the PICO Device

  1. 使用 USB 数据线将 PICO4 Ultra Enterprise 设备连接至笔记本电脑。

    Connect the PICO4 Ultra Enterprise device to the laptop using a USB cable.

  2. 将第一步中生成的 unitree_xr_teleoperate_ca.crt 文件拷贝至 PICO 设备的 Download 文件夹内。可通过系统文件管理器拖拽完成，具体操作流程可参考下方视频：

    Copy the unitree_xr_teleoperate_ca.crt file generated in Step 1 to the Download folder of the PICO device. This can be done via drag-and-drop in the system file manager. Refer to the video below for the detailed procedure:

    🎬 CA证书拷贝演示 / CA Certificate Copy Demo
    ▶ 点击在新窗口播放 Click to play in new window
    CA证书拷贝演示.mp4

6.2 通过 ADB 打开证书安装界面

6.2 Open Certificate Installation Interface via ADB

  1. 在笔记本电脑上打开终端，安装 Android Debug Bridge (ADB) 工具：

    Open a terminal on the laptop and install the Android Debug Bridge (ADB) tool:

    sudo apt install -y android-tools-adb

  2. 执行以下命令检查设备连接状态：

    Run the following command to check the device connection status:

    adb devices

    • 若输出显示 unauthorized，请佩戴 PICO 设备，在头显内弹出的“允许 USB 调试”对话框中点击 “允许”。随后再次执行 adb devices，确认状态变为 device。

      If the output shows unauthorized, wear the PICO device and tap "Allow" in the "Allow USB debugging" dialog that appears inside the headset. Then re-run adb devices to confirm the status changes to device.

    • 预期成功输出示例：

      Expected successful output:

      List of devices attached
XXXXXXXXXXXXXXXX	device

  3. 执行以下命令，直接打开 PICO 设备的证书存储设置界面：

    Execute the following command to directly open the credential storage settings interface on the PICO device:

    adb shell am start -n com.android.settings/.Settings$CredentialStorage

6.3 在 PICO 头显内完成证书安装

6.3 Complete Certificate Installation Inside the PICO Headset

上一步执行后，PICO 头显内将显示证书存储界面。请按照下方视频演示完成导入操作：

After executing the previous step, the credential storage interface will appear inside the PICO headset. Follow the demonstration in the video below to complete the import:

🎬 证书安装操作演示 / Certificate Installation Demo
▶ 点击在新窗口播放 Click to play in new window
证书安装操作演示.mp4

安装完成后，PICO 设备已信任由 unitree_xr_teleoperate_ca 签发的所有证书。后续访问 xr_teleoperate 遥操作服务时，将不再出现证书安全警告。

Once installed, the PICO device trusts all certificates signed by unitree_xr_teleoperate_ca. When accessing the xr_teleoperate teleoperation service thereafter, no certificate security warnings will appear.

🧭 Navigation

Clone this wiki locally