Secure Channel v2 Protocol
Protocol Identity
| Property | Value |
|---|---|
| Magic | SC |
| Version | 2 |
| Content-Type | application/json;charset=UTF-8 |
Message Types
| Constant | Value | Description |
|---|---|---|
TYPE_KEY_EXCHANGE | 1 | 首次握手类型, 包含加密的 AES 密钥. |
TYPE_SESSION_DATA | 2 | 会话复用类型, 不再携带 RSA 加密密钥. |
TYPE_RESPONSE_DATA | 129 | 响应数据类型, 返回时使用会话密钥加密. |
Key Sizes
| Constant | Bytes | Description |
|---|---|---|
KEY_ID_LEN_SIZE | 1 | KEY_ID 长度字段大小, 使用 1 字节保证足够紧凑. |
REQ_KEY_LEN_SIZE | 2 | REQ_KEY 长度字段大小, 使用 2 字节编码长度. |
RESP_KEY_LEN_SIZE | 2 | RESP_KEY 长度字段大小, 使用 2 字节编码长度. |
Protocol Headers
| Header | Constant |
|---|---|
X-SC-Session-Id | SESSION_ID_HEADER |
X-SC-Version | VERSION_HEADER |
SDK Methods
getPublicKey()
Returns: RsaPublicKeyInfo
获取用于客户端密钥交换的活跃 RSA 公钥.
getActiveKeyId()
Returns: String
获取活跃的 RSA 密钥 ID.
rotateKeys()
Returns: void
轮换 RSA 密钥.
decrypt(byte[])
Returns: DecryptionResult
解密 SCv2 信封格式的加密负载.
decrypt(byte[], String)
Returns: DecryptionResult
使用可选的会话复用解密加密负载.
encrypt(byte[], String)
Returns: byte[]
使用会话的 AES 密钥加密响应负载.
encrypt(byte[], SessionContext)
Returns: byte[]
使用现有会话上下文加密响应负载.
encryptPayload(byte[], SessionContext)
Returns: AesGcmCipher.GcmPayload
Encrypts a response payload using the session response key.
decryptPayload(AesGcmCipher.GcmPayload, String)
Returns: byte[]
Decrypts a request payload using the session request key.
createSession(String, String, String)
Returns: SessionContext
从加密的 AES 密钥创建会话.
getSession(String)
Returns: Optional<SessionContext>
根据 ID 获取现有会话.
isSessionValid(String)
Returns: boolean
检查会话是否存在且有效.
invalidateSession(String)
Returns: void
使会话失效.
clearAllSessions()
Returns: void
清除所有会话.
getConfig()
Returns: SecureChannelConfig
获取 SDK 配置.
bindSessionToUser(String, String)
Returns: void
将未绑定的 KEY_EXCHANGE 会话绑定到已认证用户, 并执行按用户限额检查.
isEncryptedPayload(byte[])
Returns: boolean
Check if a payload appears to be encrypted using SCv2 format.
sessionTtl(Duration)
Returns: Builder
设置会话 TTL(生存时间).
maxSessions(int)
Returns: Builder
设置每用户最大会话数.
sessionStore(SessionStore)
Returns: Builder
设置自定义会话存储实现.
keyStore(KeyStore)
Returns: Builder
设置自定义密钥存储实现.
build()
Returns: SecureChannelSDK
构建 SDK 实例.