harmony(鸿蒙)TLSSocket

2022-10-28
浏览 (998)

TLSSocket

TLS Socket通信是对Socket通信的拓展。在Socket通信的基础上添加了一层安全性保护，提供了更高的安全性，分为三个子模块，包括密钥，证书，通信。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import socket from '@ohos.net.tlssocket'

socket.constructTLSSocketInstance

constructTLSSocketInstance(): TLSSocket

创建并返回一个TLSSocket对象。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

示例：

let tlssocket = socket.constructTLSSocketInstance();

tlssocket.connect

connect(options: TLSConnectOptions, callback: AsyncCallback<void>): void

在TLSSocket上进行通信连接，并创建和初始化TLS会话，实现建立连接过程，启动与服务器的TLS/SSL握手，实现数据传输功能，使用callback方式作为异步方法。

参数：

参数名	类型	必填	说明
options	TLSConnectOptions	是	连接所需要的参数。
callback	AsyncCallback<void>	是	回调函数，成功无返回，失败返回对应错误码。

示例：

let options = {
            ALPNProtocols: ["spdy/1", "http/1.1"],
            address: {
                address: "xxx",
                port: "xxxx",
                family: 1,
            },
            secureOptions: {
                key: "xxxx",
                cert: "xxxx",
                ca: ["xxxx"],
                passwd: "xxxx",
                protocols: "TlsV1_2",
                useRemoteCipherPrefer: true,
                signatureAlgorithms: SHA256,
                cipherSuites: AES256-SHA256,
            },
};

tlssocket.connect(options, (err, data) => {
    console.info(err);
    console.info(data);
});

tlssocket.connect

connect(options: TLSConnectOptions): Promise<void>;

在TLSSocket上进行通信连接，并创建和初始化TLS会话，实现建立连接过程，启动与服务器的TLS/SSL握手，实现数据传输功能，使用Promise方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
options	TLSConnectOptions	是	连接所需要的参数。

返回值：

类型	说明
Promise<void>	以Promise形式返回，成功无返回，失败返回对应错误码。

示例：

let options = {
            ALPNProtocols: ["spdy/1", "http/1.1"],
            address: {
                address: "xxxx",
                port: "xxxx",
                family: 1,
            },
            secureOptions: {
                key: "xxxx",
                cert: "xxxx",
                ca: ["xxxx"],
                passwd: "xxxx",
                protocols: "TlsV1_2",
                useRemoteCipherPrefer: true,
                signatureAlgorithms: SHA256,
                cipherSuites: AES256-SHA256,
            },
};

tlssocket.connect(options).then(data => {
    console.info(data);
}).catch(err => {
    console.error(err);
});

tlssocket.getCertificate

getCertificate(callback: AsyncCallback<string>): void;

在TLSSocket通信连接之后，获取本地的数字证书，使用callback方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
callback	AsyncCallback<string>	是	回调函数，返回本地的证书。

示例：

tlssocket.getCertificate((err, data) => {
  if (err) {
    console.log("getCertificate callback error = " + err);
  } else {
    console.log("getCertificate callback = " + data);
  }
});

tlssocket.getCertificate

getCertificate():Promise<string>;

在TLSSocket通信连接之后，获取本地的数字证书，使用Promise方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

返回值：

类型	说明
Promise<string>	以Promise形式返回本地的数字证书。

示例：

tlssocket.getCertificate().then(data => {
  console.info(data);
}).catch(err => {
  console.error(err);
});

tlssocket.getRemoteCertificate

getRemoteCertificate(callback: AsyncCallback<string>): void;

在TLSSocket通信连接之后，获取对等方的数字证书，使用callback方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
callback	AsyncCallback<string>	是	回调函数，返回对等方的证书。

示例：

tlssocket.getRemoteCertificate((err, data) => {
  if (err) {
    console.log("getRemoteCertificate callback error = " + err);
  } else {
    console.log("getRemoteCertificate callback = " + data);
  }
});

tlssocket.getRemoteCertificate

getRemoteCertificate():Promise<string>;

在TLSSocket通信连接之后，获取对等方的数字证书，使用Promise方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

返回值：

类型	说明
Promise<string>	以Promise形式返回对等方的数字证书。

示例：

tlssocket.getRemoteCertificate().then(data => {
  console.info(data);
}).catch(err => {
  console.error(err);
});

tlssocket.getProtocol

getProtocol(callback: AsyncCallback<string>): void;

在TLSSocket通信连接之后，获取通信的协议，使用callback方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
callback	AsyncCallback<string>	是	回调函数，返回通信的协议。

示例：

tlssocket.getProtocol((err, data) => {
  if (err) {
    console.log("getProtocol callback error = " + err);
  } else {
    console.log("getProtocol callback = " + data);
  }
});

tlssocket.getProtocol

getProtocol():Promise<string>;

在TLSSocket通信连接之后，获取通信的协议，使用Promise方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

返回值：

类型	说明
Promise<string>	以Promise形式返回通信的协议。

示例：

tlssocket.getProtocol().then(data => {
  console.info(data);
}).catch(err => {
  console.error(err);
});

tlssocket.getCipherSuites

getCipherSuites(callback: AsyncCallback<Array<string>>): void;

在TLSSocket通信连接之后，获取通信双方支持的加密套件，使用callback方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Array<string>>	是	回调函数，返回通信双方支持的加密套件。

示例：

tlssocket.getCipherSuites((err, data) => {
  if (err) {
    console.log("getCipherSuites callback error = " + err);
  } else {
    console.log("getCipherSuites callback = " + data);
  }
});

tlssocket.getCipherSuites

getCipherSuites(): Promise<Array<string>>;

在TLSSocket通信连接之后，获取通信双方支持的加密套件，使用Promise方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

返回值：

类型	说明
Promise<Array<string>>	以Promise形式返回通信双方支持的加密套件。

示例：

tlssocket.getCipherSuites().then(data => {
  console.info(data);
}).catch(err => {
  console.error(err);
});

tlssocket.getSignatureAlgorithms

getSignatureAlgorithms(callback: AsyncCallback<Array<string>>): void;

在TLSSocket通信连接之后，获取通信双方支持的签名算法，使用callback方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
callback	AsyncCallback<Array<string>>	是	回调函数，返回双方支持的签名算法。

示例：

tlssocket.getSignatureAlgorithms((err, data) => {
  if (err) {
    console.log("getSignatureAlgorithms callback error = " + err);
  } else {
    console.log("getSignatureAlgorithms callback = " + data);
  }
});

tlssocket.getSignatureAlgorithms

getSignatureAlgorithms(): Promise<Array<string>>;

在TLSSocket通信连接之后，获取通信双方支持的签名算法，使用Promise方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

返回值：

类型	说明
Promise<Array<string>>	以Promise形式返回获取到的双方支持的签名算法。

示例：

tlssocket.getSignatureAlgorithms().then(data => {
  console.info(data);
}).catch(err => {
  console.error(err);
});

tlssocket.close

close(callback: AsyncCallback<void>): void;

在TLSSocket通信连接之后，断开连接，使用callback方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数,返回TLSSocket关闭连接的结果。

示例：

tlssocket.close((err) => {
  if (err) {
    console.log("close callback error = " + err);
  } else {
    console.log("close success");
  }
});

tlssocket.close

close(): Promise<void>;

在TLSSocket通信连接之后，断开连接，使用Promise方式作为异步方法。

需要权限：ohos.permission.INTERNET

系统能力：SystemCapability.Communication.NetStack

返回值：

类型	说明
Promise<void>	以Promise形式返回,返回TLSSocket关闭连接的结果。

示例：

tlssocket.close().then(() =>
  console.log("close success");
}).catch(err => {
  console.error(err);
});

TLSConnectOptions

TLS连接的操作。

系统能力：SystemCapability.Communication.NetStack

参数名	类型	说明
address	NetAddress	网关地址。
secureOptions	TLSSecureOptions	TLS安全相关操作。
ALPNProtocols	Array<string>	ALPN协议。

NetAddress

网络地址。

系统能力：SystemCapability.Communication.NetStack

参数名	类型	说明
address	string	地址。
family	number	IPv4 = 1，IPv6 = 2，默认IPv4。
port	number	端口，取值范围[0, 65535]。

TLSSecureOptions

TLS安全相关操作。

系统能力：SystemCapability.Communication.NetStack

参数名	类型	说明
ca	string \|Array<string>	ca证书。
cert	string	本地数字证书。
key	string	本地数字证书私钥。
passwd	string	密码。
protocols	string	协议名。
useRemoteCipherPrefer	boolean	优先使用对等方的密码套件。
signatureAlgorithms	string	设置签名算法。
cipherSuites	string	加密套件。