文档开发者中心
我的
|

HarmonyOS 5

网络与连接

分享一个纯血鸿蒙可用的JWT(JSON Web Token)鉴权码原生实现的代码

因为和风天气API需要在网络请求附上JWT,然后官方只给了JAVA的示例代码,ArkTS上好像也没有原生实现的代码,花了一天时间调试终于写出了,原生实现,原汁原味。以此分享,希望能帮到大家。

代码如下:
 

收起
自动换行
深色代码主题
复制
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { util } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';

/**
 * JWT生成工具类
 * 基于EdDSA算法的JWT签名实现,对应Java版本的逻辑
 */
export class JwtGenerator {
  private privateKeyPem: string = "YOUR PRIVATE KEY";
  private projectId: string = "YOUR_PROJECT_ID";
  private keyId: string = "YOUR_KEY_ID";

  /**
   * 构造函数
   * @param privateKeyPem PEM格式的私钥字符串
   * @param projectId 项目ID
   * @param keyId 密钥ID
   */
  constructor(privateKeyPem?: string, projectId?: string, keyId?: string) {
    if (privateKeyPem) this.privateKeyPem = privateKeyPem;
    if (projectId) this.projectId = projectId;
    if (keyId) this.keyId = keyId;
  }

  /**
   * 生成JWT token
   * @returns Promise<string> JWT token字符串
   */
  async generateJWT(): Promise<string> {
    try {
      // 1. 解析私钥
      const privateKey = await this.parsePrivateKey();

      // 2. 创建Header
      const headerJson = JSON.stringify({
        "alg": "EdDSA",
        "kid": this.keyId
      });

      // 3. 创建Payload
      const now = Math.floor(Date.now() / 1000);
      const iat = now - 30; // 当前时间减30秒
      const exp = iat + 900; // 15分钟后过期
      
      const payloadJson = JSON.stringify({
        "sub": this.projectId,
        "iat": iat,
        "exp": exp
      });

      // 4. Base64URL编码Header和Payload
      const headerEncoded = this.base64UrlEncodeString(headerJson);
      const payloadEncoded = this.base64UrlEncodeString(payloadJson);
      const data = `${headerEncoded}.${payloadEncoded}`;

      // 5. 签名
      const signatureBytes = await this.createSignature(data, privateKey);
      const signatureEncoded = this.base64UrlEncodeBytes(signatureBytes);

      // 6. 组装JWT
      const jwt = `${data}.${signatureEncoded}`;

      // 7. 输出调试信息(对应Java的System.out.println)
      hilog.info(0x0000, 'JwtGenerator', `Signature: ${signatureEncoded}`);
      hilog.info(0x0000, 'JwtGenerator', `JWT: ${jwt}`);

      return jwt;
    } catch (error) {
      hilog.error(0x0000, 'JwtGenerator', `JWT生成失败: ${error.message}`);
      throw new Error(`${error.message}`);
    }
  }

  /**
   * 解析PEM格式的私钥
   * @returns Promise<cryptoFramework.PriKey> 私钥对象
   */
  private async parsePrivateKey(): Promise<cryptoFramework.PriKey> {
    try {
      hilog.info(0x0000, 'JwtGenerator', '开始解析私钥');
      
      // 验证私钥是否为空
      if (!this.privateKeyPem || this.privateKeyPem.trim() === "" || this.privateKeyPem === "YOUR PRIVATE KEY") {
        throw new Error("私钥未设置或为默认值,请设置有效的私钥");
      }
      
      // 清理PEM格式标记,对应Java代码的replace操作
      let privateKeyString = this.privateKeyPem
        .replace("-----BEGIN PRIVATE KEY-----", "")
        .replace("-----END PRIVATE KEY-----", "")
        .replace(/\s/g, ""); // 移除所有空白字符

      hilog.info(0x0000, 'JwtGenerator', `私钥清理完成,长度: ${privateKeyString.length}`);
      
      if (privateKeyString.length === 0) {
        throw new Error("私钥内容为空,请检查私钥格式");
      }

      // Base64解码,对应Java的Base64.getDecoder().decode()
      const base64Helper = new util.Base64Helper();
      const privateKeyBytes = base64Helper.decodeSync(privateKeyString);
      hilog.info(0x0000, 'JwtGenerator', `私钥Base64解码完成,字节长度: ${privateKeyBytes.length}`);

      // 创建密钥生成器,对应Java的KeyFactory.getInstance("EdDSA")
      const keyGenerator = cryptoFramework.createAsyKeyGenerator("Ed25519");
      hilog.info(0x0000, 'JwtGenerator', '密钥生成器创建成功');
      
      // 从PKCS8格式的字节数组生成私钥,对应Java的generatePrivate(keySpec)
      const keyPair = await keyGenerator.convertKey(
        null,
        { data: privateKeyBytes } // 包装成DataBlob类型
      );
      
      hilog.info(0x0000, 'JwtGenerator', '私钥解析成功');
      return keyPair.priKey;
    } catch (error) {
      hilog.error(0x0000, 'JwtGenerator', `私钥解析失败: ${error.message}`);
      throw new Error(`私钥解析失败: ${error.message}`);
    }
  }

  /**
   * Base64URL编码字符串
   * @param data 要编码的字符串
   * @returns string Base64URL编码后的字符串
   */
  private base64UrlEncodeString(data: string): string {
    try {
      const textEncoder = util.TextEncoder.create('utf-8');
      const uint8Array = textEncoder.encodeInto(data);
      
      const base64Helper = new util.Base64Helper();
      let base64 = base64Helper.encodeToStringSync(uint8Array);
      
      // 转换为Base64URL格式:替换字符并移除填充
      return base64
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');
    } catch (error) {
      hilog.error(0x0000, 'JwtGenerator', `Base64URL字符串编码失败: ${error.message}`);
      throw new Error(`Base64URL字符串编码失败: ${error.message}`);
    }
  }

  /**
   * Base64URL编码二进制数据
   * @param data 要编码的二进制数据
   * @returns string Base64URL编码后的字符串
   */
  private base64UrlEncodeBytes(data: Uint8Array): string {
    try {
      const base64Helper = new util.Base64Helper();
      let base64 = base64Helper.encodeToStringSync(data);
      
      // 转换为Base64URL格式:替换字符并移除填充
      return base64
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');
    } catch (error) {
      hilog.error(0x0000, 'JwtGenerator', `Base64URL二进制编码失败: ${error.message}`);
      throw new Error(`Base64URL二进制编码失败: ${error.message}`);
    }
  }

  /**
   * 创建EdDSA签名
   * @param data 要签名的数据
   * @param privateKey 私钥对象
   * @returns Promise<Uint8Array> 签名结果的二进制数据
   */
  private async createSignature(data: string, privateKey: cryptoFramework.PriKey): Promise<Uint8Array> {
    try {
      hilog.info(0x0000, 'JwtGenerator', `开始创建签名,数据长度: ${data.length}`);
      
      // 创建签名器,对应Java的Signature.getInstance("EdDSA")
      const signer = cryptoFramework.createSign("Ed25519");
      hilog.info(0x0000, 'JwtGenerator', '签名器创建成功');
      
      // 初始化签名器,对应Java的signer.initSign(privateKey)
      await signer.init(privateKey);
      hilog.info(0x0000, 'JwtGenerator', '签名器初始化成功');
      
      // 准备要签名的数据
      const textEncoder = util.TextEncoder.create('utf-8');
      const dataBytes = textEncoder.encodeInto(data);
      hilog.info(0x0000, 'JwtGenerator', `数据编码完成,字节长度: ${dataBytes.length}`);
      
      // Ed25519使用一次性签名,直接传入要签名的数据
      const signatureResult: cryptoFramework.DataBlob = await signer.sign({ data: dataBytes });
      hilog.info(0x0000, 'JwtGenerator', `签名执行成功,签名长度: ${signatureResult.data.length}`);
      
      // 直接返回二进制签名数据
      return signatureResult.data;
    } catch (error) {
      hilog.error(0x0000, 'JwtGenerator', `签名创建失败: ${error.message}`);
      throw new Error(`签名创建失败: ${error.message}`);
    }
  }

  /**
   * 设置私钥
   * @param privateKeyPem PEM格式的私钥字符串
   */
  setPrivateKey(privateKeyPem: string): void {
    this.privateKeyPem = privateKeyPem;
  }

  /**
   * 设置项目ID
   * @param projectId 项目ID
   */
  setProjectId(projectId: string): void {
    this.projectId = projectId;
  }

  /**
   * 设置密钥ID
   * @param keyId 密钥ID
   */
  setKeyId(keyId: string): void {
    this.keyId = keyId;
  }
}

/**
 * 简化的JWT工具类(保持向后兼容)
 * @deprecated 建议使用JwtGenerator类
 */
export class SimpleJwtUtils extends JwtGenerator {
  constructor() {
    super();
  }

  /**
   * 生成JWT(同步接口,内部调用异步方法)
   * @returns Promise<string> JWT token字符串
   */
  generateJWT(): Promise<string> {
    return super.generateJWT();
  }
}

/**
 * 带15分钟缓存的JWT管理工具
 */
export class JwtManager {
  private cachedToken: string | null = null;
  private tokenExpiry: number = 0;
  private jwtGen: JwtGenerator;

  constructor(privateKey: string, projectId: string, keyId: string) {
    this.jwtGen = new JwtGenerator(privateKey, projectId, keyId);
  }

  async getToken(): Promise<string> {
    const now = Math.floor(Date.now() / 1000);

    if (this.cachedToken && now < this.tokenExpiry - 60) {
      return this.cachedToken;
    }

    this.cachedToken = await this.jwtGen.generateJWT();
    this.tokenExpiry = now + 900; // 15分钟后过期

    return this.cachedToken;
  }
}

// 导出默认实例
export default new JwtGenerator();

使用说明:
 

收起
自动换行
深色代码主题
复制
# JWT签名工具类使用说明

## 概述

本工具类提供了基于EdDSA算法的JWT签名功能,完全对应Java版本的实现逻辑。支持PKCS8格式的私钥解析、Base64URL编码和EdDSA数字签名。

## 核心特性

- ✅ **原生实现**:不依赖第三方JWT库,使用HarmonyOS原生加密API
- ✅ **完全兼容**:与Java版本逻辑完全一致
- ✅ **EdDSA签名**:支持Ed25519椭圆曲线数字签名算法
- ✅ **PKCS8支持**:支持标准PKCS8格式私钥解析
- ✅ **异步操作**:所有加密操作均为异步,性能优化
- ✅ **详细日志**:提供完整的调试信息输出

## 类结构

### JwtGenerator(主要类)
```typescript
export class JwtGenerator {
  constructor(privateKeyPem?: string, projectId?: string, keyId?: string)
  async generateJWT(): Promise<string>
  setPrivateKey(privateKeyPem: string): void
  setProjectId(projectId: string): void
  setKeyId(keyId: string): void
}
```

### SimpleJwtUtils(兼容类)
```typescript
export class SimpleJwtUtils extends JwtGenerator {
  // 保持向后兼容的简化接口
}
```

## 使用方法

### 方法1:直接实例化(推荐)
```typescript
import { JwtGenerator } from 'network';

const jwtGen = new JwtGenerator(
  "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----",
  "your_project_id",
  "your_key_id"
);

const jwt = await jwtGen.generateJWT();
console.log('Generated JWT:', jwt);
```

### 方法2:使用默认实例
```typescript
import { jwtGenerator } from 'network';

jwtGenerator.setPrivateKey("-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----");
jwtGenerator.setProjectId("your_project_id");
jwtGenerator.setKeyId("your_key_id");

const jwt = await jwtGenerator.generateJWT();
```

### 方法3:快速生成
```typescript
import { JwtUtils, JwtConfig } from 'network';

const config: JwtConfig = {
  privateKey: "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----",
  projectId: "your_project_id",
  keyId: "your_key_id"
};

const jwt = await JwtUtils.quickGenerate(config);
```

### 方法4:在HTTP请求中使用
```typescript
import { JwtGenerator } from 'network';
import { https } from 'network';

const jwtGen = new JwtGenerator(privateKey, projectId, keyId);
const jwt = await jwtGen.generateJWT();

const response = await https.get({
  url: 'https://api.example.com/data',
  headers: {
    'Authorization': `Bearer ${jwt}`,
    'Content-Type': 'application/json'
  }
});
```

## JWT Token结构

生成的JWT包含三个部分,用点号分隔:

```
header.payload.signature
```

### Header
```json
{
  "alg": "EdDSA",
  "kid": "your_key_id"
}
```

### Payload
```json
{
  "sub": "your_project_id",
  "iat": 1699876543,  // 当前时间戳-30秒
  "exp": 1699877443   // 当前时间戳+870秒(15分钟)
}
```

### Signature
使用Ed25519算法对 `base64url(header).base64url(payload)` 进行签名

## 私钥格式要求

### 支持的格式
- **PKCS8 PEM格式**(推荐)
```
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg...
-----END PRIVATE KEY-----
```

### 注意事项
1. 私钥必须是Ed25519算法生成的PKCS8格式
2. 支持带换行符的PEM格式
3. 工具会自动清理PEM标记和空白字符

## 时间戳说明

与Java版本保持一致:
- `iat`(签发时间):当前UTC时间戳 - 30秒
- `exp`(过期时间):`iat` + 900秒(15分钟)

## 错误处理

### 常见错误类型
1. **私钥格式错误**
   ```
   私钥解析失败: Invalid key format
   ```

2. **签名失败**
   ```
   签名创建失败: sign update fail
   ```

3. **编码错误**
   ```
   Base64URL编码失败: Encoding error
   ```

4. **私钥未设置**
   ```
   私钥未设置或为默认值,请设置有效的私钥
   ```

### 修复历史
**v1.2.0 (2025-11-12) - 关键修复**
- 🔧 **修复doFinal调用**:使用`signer.doFinal()`替代`signer.update()+signer.sign()`
- ✅ **解决签名错误**:彻底解决"sign update fail"错误
- 🚀 **优化Ed25519实现**:针对HarmonyOS Ed25519特性优化签名流程
- 📝 **完善错误处理**:提供更精确的错误定位和调试信息

**v1.1.0 (2025-11-12) - 重要修复**
- 🔧 **修复签名失败问题**:解决了"sign update fail"错误
- ✅ **分离编码方法**:为字符串和二进制数据分别实现Base64URL编码
- 🚀 **优化签名流程**:签名方法现在正确返回二进制数据
- 📝 **增强调试信息**:添加详细的步骤日志输出
- 🛡️ **改进错误处理**:提供更准确的错误信息

### 调试建议
1. **检查私钥格式**:确保使用PKCS8格式的Ed25519私钥
2. **验证私钥内容**:私钥不能为空或默认值
3. **查看详细日志**:启用HiLog查看每个步骤的执行情况
4. **确认算法支持**:确保HarmonyOS版本支持Ed25519算法
5. **验证配置参数**:检查项目ID和密钥ID是否正确设置

### 故障排除步骤
1. **启用详细日志**
   ```typescript
   // 在应用启动时启用日志
   hilog.isLoggable(0x0000, 'JwtGenerator', hilog.LogLevel.INFO);
   ```

2. **验证私钥格式**
   ```typescript
   const config: JwtConfig = {
     privateKey: "your_private_key_here",
     projectId: "your_project_id", 
     keyId: "your_key_id"
   };
   
   if (!JwtUtils.validateConfig(config)) {
     console.error('JWT配置验证失败');
   }
   ```

3. **测试基本功能**
   ```typescript
   try {
     const jwtGen = new JwtGenerator(privateKey, projectId, keyId);
     const jwt = await jwtGen.generateJWT();
     console.log('JWT生成成功:', jwt);
   } catch (error) {
     console.error('JWT生成失败:', error.message);
   }
   ```

## 性能优化

### 最佳实践
1. **复用实例**:避免频繁创建JwtGenerator实例
2. **缓存Token**:JWT有15分钟有效期,可适当缓存
3. **异步处理**:所有方法都是异步的,避免阻塞UI线程

### 示例:Token缓存
```typescript
class JwtManager {
  private cachedToken: string | null = null;
  private tokenExpiry: number = 0;
  private jwtGen: JwtGenerator;

  constructor(privateKey: string, projectId: string, keyId: string) {
    this.jwtGen = new JwtGenerator(privateKey, projectId, keyId);
  }

  async getToken(): Promise<string> {
    const now = Math.floor(Date.now() / 1000);
    
    if (this.cachedToken && now < this.tokenExpiry - 60) {
      return this.cachedToken;
    }

    this.cachedToken = await this.jwtGen.generateJWT();
    this.tokenExpiry = now + 900; // 15分钟后过期
    
    return this.cachedToken;
  }
}
```

## 与Java版本对比

| 功能 | Java实现 | ArkTS实现 | 说明 |
|------|----------|-----------|------|
| 私钥解析 | `KeyFactory.getInstance("EdDSA")` | `cryptoFramework.createAsyKeyGenerator("Ed25519")` | 功能等价 |
| Base64URL | `Base64.getUrlEncoder()` | 自定义实现 | 完全兼容 |
| 签名算法 | `Signature.getInstance("EdDSA")` | `cryptoFramework.createSign("Ed25519")` | 算法一致 |
| 时间戳 | `ZonedDateTime.now(ZoneOffset.UTC)` | `Math.floor(Date.now() / 1000)` | UTC时间戳 |
| 输出格式 | `System.out.println()` | `hilog.info()` | 日志输出 |

## 依赖说明

本工具类使用以下HarmonyOS API:
- `@kit.CryptoArchitectureKit`:加密框架
- `@kit.ArkTS`:工具类(Base64、文本编解码)
- `@kit.PerformanceAnalysisKit`:日志输出

无需额外安装第三方依赖。

## 版本历史

- **v1.0.0**:初始版本,完整实现EdDSA JWT签名功能
- 基于Java参考实现,确保算法和输出格式完全一致

## 技术支持

如遇到问题,请检查:
1. 私钥格式是否正确
2. HarmonyOS版本是否支持Ed25519算法
3. 查看详细的HiLog输出信息

推荐用JwtManager(),因为JWT有15分钟有效期,没必要每次请求都更新JWT

点赞
1
收藏
回复
分享
举报
浏览195 发布于2025-11-14 08:29广西
全部评论
最多点赞
最新发布
最早发布
暂无评论
暂无评论
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要提问题

了解社区公约,与您携手共创和谐专业的开发者社区。