immudb-py

Python 的官方immudb客户端。

在 immudb Playground 上试试吧！

内容

• 介绍
• 先决条件
• 安装
• 支持的版本
• 快速开始
• 分步指南
• 创建客户端

介绍

immu -py 实现了一个grpc immudb 客户端。为应用程序公开了一个极简 API，而密码验证和状态更新协议实现完全由该客户端实现。使用默认值时，最新验证的 immudb 状态可能会保存在本地文件系统中rootService，请阅读immudb 研究论文了解immudb如何确保不可变性的详细信息。

先决条件

immu-py 假设有一个现有的 immudb 服务器实例启动并运行。运行immudb很简单，下载运行请参考以下链接：https ://immudb.io/docs/quickstart.html

immudb-py 需要 python 3.6 或更高版本。如果您使用的是 3.6，则需要 dataclasses 包；在 3.7+ 上，数据类是 python 发行版的一部分。

安装

您可以安装克隆此存储库的最新版本，然后使用 make 命令安装先决条件和包本身：

    make init
    make install

或者，您可以使用 pip 安装最新的稳定版本：

    pip3 install immudb-py

然后，在您的代码中，按如下方式导入客户端库：

    from immudb import ImmudbClient

注意：immudb-py 需要grpcio来自 google 的模块。在 Alpine linux 上，您需要这些软件包才能正确构建（和安装）grpcio：

• linux-headers
• python3-dev
• g++

支持的版本

immu -py 支持最新的 immudb 版本。

快速开始

你好，不变的世界！示例可以在immudb-client-examplesrepo 中找到。

分步指南

创建客户端

以下代码片段显示了如何创建客户端。

使用默认配置：

    client = ImmudbClient()

设置immudb网址和端口：

    client = ImmudbClient("mycustomurl:someport")
    client = ImmudbClient("10.105.20.32:8899")

用户会话

启动和终止用户会话的用途login和logout方法：

    client.login("usr1", "pwd1");

    // Interact with immudb using logged user

    client.logout();

编码

请注意，为了提供最大的灵活性，所有函数都接受字节数组作为参数。因此，必须正确编码 unicode 字符串。可以存储结构化对象，但必须对它们进行序列化（例如，使用 pickle 或 json）。

创建数据库

创建一个新数据库非常简单：

    client.createDatabase(b"db1");

设置活动数据库

指定活动数据库：

    client.useDatabase(b"db1");

如果未指定，则使用的默认数据库为“defaultdb”。

传统读写

immudb 提供读取和写入操作，其行为类似于传统的键值存储，即不进行加密验证。当验证可以推迟时，可以使用此操作：

    client.set(b"k123", b"value123");
    result = client.get(b"k123");

验证读写

immudb 为任何条目提供内置的加密验证。客户端实现数学验证，而应用程序用作传统的读取或写入操作：

    try:
        client.verifiedSet(b"k123", b"v123");
        results = client.verifiedGet(b"k123");
    Except VerificationException as e:
        # Do something

多键读写

immudb 和 immudb-py 支持事务性多键读写操作。原子多键写入（所有条目都被持久化或没有）：

    normal_dictionary = {b"key1": b"value1", b"key2": b"value2"}
    client.setAll(normal_dictionary);

原子多键读取（检索所有条目或不检索）：

    normal_dictionary = {b"key1": b"value1", b"key2": b"value2"}
    results_dictionary = client.getAll(normal_dictionary.keys())
    # Or manually
    client.get([b"key1", b"key2"])

用户管理

可以添加用户并授予对数据库的访问权限。

添加用户

这些createUser函数创建一个新用户并向数据库授予指定的权限。

user='newuser'
password='Pw1:pasdfoiu'
permission=immudb.constants.PERMISSION_RW
database='defaultdb'

client.createUser(user, password, permission, database)

数据库必须在创建用户时存在。密码长度必须介于 8 到 32 个字符之间，并且必须至少包含一个大写字母、一个符号和一个数字。

权限在 immudb.constants 中定义，包括：

• PERMISSION_SYS_ADMIN
• PERMISSION_ADMIN
• PERMISSION_NONE
• PERMISSION_R
• PERMISSION_RW

更改密码

用户必须同时提供旧密码和新密码：

newPassword="pW1:a0s98d7gfy"
resp=client.changePassword(user, newPassword, oldPassword)

它应用与用户创建相同的密码策略。

用户列表

要获取在 immudb 上创建的用户列表，只需调用listUsers：

resp=client.listUsers()
print(users.userlist.users)

关闭客户端

要以编程方式关闭与 immudb 服务器的连接，请使用以下shutdown操作：

    client.shutdown();

注意：关机后，需要创建一个新的客户端来建立新的连接。

状态持久化

immudb 的一个重要特性是客户端能够检查每笔交易是否被篡改。为了能够做到这一点，有必要保持客户端状态（即，将其保存到磁盘），以便如果在两次运行之间发生服务器上的某些篡改，可以立即检测到。

ARootService实现了这一点：它在每次事务之后存储 immudb 客户端，以便之后能够使用它来检查服务器的正确性。

使用持久根服务

为简单起见，默认的 RootService 将状态提交到 RAM，因此它不适合实时安全应用程序。为了具有持久性，应用程序必须实例化一个PersistentRootService对象，该对象将其状态存储到磁盘。

让我们看一个使用状态持久性的简单示例：

from immudb.client import ImmudbClient, PersistentRootService
client=ImmudbClient(rs=PersistentRootService())
client.login(username="immudb", password="immudb")
client.verifiedTxById(42)
client.verifiedGet(b"example")

在此示例中，根服务在每次验证事务后保存到磁盘。如您所见，它非常易于使用。只需在客户端初始化中创建并使用 PersistentRootService 对象。

进程和线程

请记住，实现不是线程/进程安全的。如果您使用的是多进程应用程序，建议为每个实例使用不同的状态文件：只需将文件名作为参数传递给 PersistentRootService 构造函数：

client = ImmudbClient(rs=PersistentRootService("rootfilename"))

默认根文件是“~/.immudbRoot”

如果需要/想要，也可以轻松扩展默认实现，将同步原语添加到 get/set 方法。这样，多个 immudb 客户端可以共享同一个 PersistentRootService 实例，而不会相互干扰。

加密状态签名

为了提高安全性，可以生成一个私钥并使用它来签署每个验证响应。然后客户端可以使用相应的公钥来检查响应的正确性。

密钥生成

您可以使用openssl创建私钥，然后提取公钥：

openssl ecparam -name prime256v1 -genkey -noout -out private_signing_key.pem
openssl ec -in private_signing_key.pem -pubout -out public_signing_key.pem

密钥使用（服务器端）

在 immudb 服务器上，用于--signingKey private_signing_key.pem激活加密签名。

密钥使用（客户端/SDK 端）

在 immudb python SDK 上，只需将公钥文件名传递给 ImmudbClient 构造函数：

client=ImmudbClient(publicKeyFile="/certs/public_signing_key.pem")

然后将自动检查每笔交易。如果密码检查失败，则会引发异常。

贡献

我们欢迎贡献。随时加入团队！

要报告错误或获得帮助，请使用GitHub 的问题。