README

简介 | SDK 功能 | 安装 | 配置 SDK | 使用示例 | 文档 | 支持

简介

Virgil Security 为添加安全性到任何应用程序提供了一套 API。只需几个简单步骤，您就可以加密通信、安全存储数据并确保数据完整性。Virgil Security 的产品适用于桌面、嵌入式（IoT）、移动、云和 Web 应用程序，支持多种现代编程语言。

Virgil Core SDK 是一个低级别库，允许开发者快速使用 Virgil Cards Service API，并为其新或现有数字解决方案添加端到端安全性。

如果您需要额外的安全功能以支持多设备支持、群组聊天等，请尝试我们的高级 Virgil E3Kit 框架。

SDK 功能

通过 Virgil Cards Service 进行通信
管理用户的公钥
加密、签名、解密和验证数据
在安全的本地存储中存储私钥
使用 Virgil Crypto Library

安装

Virgil Core SDK 以名为 virgil/sdk 的包提供。该包通过 Composer 包管理器系统分发。

该包适用于 PHP 版本 8.2 及更高版本。

使用包管理器控制台安装包

composer require virgil/sdk

加密扩展通知

为了支持加密操作，您还需要安装 Virgil 加密扩展。我们提供与 Virgil Core SDK 一起使用的自己的扩展，易于任何人使用。要在当前系统中自动安装扩展，只需运行以下命令

./vendor/virgil/crypto-wrapper/_extensions/setup.sh -all -vendor

请注意，crypto-wrapper 包在通过 composer 安装 virgil/sdk 后出现在您的 vendors 中。要检查 Virgil 加密扩展是否正确安装，请运行

php -m

应提供以下扩展：vsce_phe_php、vscf_foundation_php、vscp_pythia_php

注意：如果出现以下警告，则导出环境变量 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/php7/modules (/usr/lib/php7/modules - 您的 php 扩展路径可能不同)

PHP Warning:  PHP Startup: Unable to load dynamic library 'vsce_phe_php' (tried: /usr/lib/php7/modules/vsce_phe_php (Error loading shared library /usr/lib/php7/modules/vsce_phe_php: No such file or directory), /usr/lib/php7/modules/vsce_phe_php.so (Error loading shared library vscf_foundation_php.so: No such file or directory (needed by /usr/lib/php7/modules/vsce_phe_php.so))) in Unknown on line 0

LD_LIBRARY_PATH 是一个环境变量，它保留所有包含用户动态共享库的路径。

现在Virgil Core SDK已经准备好使用，让我们来配置它并运行一些示例。

配置SDK

本节包含有关如何设置用于用户身份验证、管理Virgil卡和存储私钥的Virgil Core SDK模块的指南。

设置身份验证

使用基于JSON Web Token标准的令牌设置用户身份验证，并进行一些Virgil修改。

为了调用Virgil服务（例如，在Virgil Cards服务上发布用户的卡），您需要一个包含用户身份的JSON Web Token ("JWT")，该身份是一个字符串，用于唯一标识您应用程序中的每个用户。

所需的凭证

在客户端设置JWT提供者

使用以下代码行指定您希望在项目中使用哪个JWT生成源

use Virgil\Sdk\Web\Authorization\CallbackJwtProvider;
use Virgil\Sdk\Web\Authorization\TokenContext;

$authenticatedQueryToServerSide = function (TokenContext $context){
    // Get generated token from server-side
    return "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak";
};

// Setup AccessTokenProvider
$accessTokenProvider = new CallbackJwtProvider($authenticatedQueryToServerSide);

在服务器端生成JWT

接下来，您需要设置JwtGenerator并使用Virgil SDK生成JWT。

以下是生成JWT的示例

use Virgil\Crypto\VirgilCrypto;
use Virgil\Sdk\Web\Authorization\JwtGenerator;

// App Key (you got this Key at Virgil Dashboard)
$privateKeyStr = "MC4CAQAwBQYDK2VwBCIEIH2RKUdXkK/3tfVWO2AJahOhCYG2hCEHg4mPJEAuvmj7";
$appKeyData = base64_decode($privateKeyStr);

// VirgilCrypto imports a private key into a necessary format
$crypto = new VirgilCrypto();
$privateKey = $crypto->importPrivateKey($appKeyData);

// use your App Credentials you got at Virgil Dashboard:
$appId = "be00e10e4e1f4bf58f9b4dc85d79c77a"; // App ID
$appKeyId = "70b447e321f3a0fd";              // App Key ID
$ttl = 3600; // 1 hour (JWT's lifetime)

// setup JWT generator with necessary parameters:
$jwtGenerator = new JwtGenerator($privateKey->getPrivateKey(), $appKeyId, $crypto, $appId, $ttl);

// generate JWT for a user
// remember that you must provide each user with his unique JWT
// each JWT contains unique user's identity (in this case - Alice)
// identity can be any value: name, email, some id etc.
$identity = "Alice";
$token = $jwtGenerator->generateToken($identity);

// as result you get users JWT, it looks like this: "eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak"
// you can provide users with JWT at registration or authorization steps
// Send a JWT to client-side
$token->__toString();

对于本小节，我们创建了一个示例后端，演示了如何设置您的后端以生成JWT。要本地设置和运行示例后端，请访问您选择的GitHub仓库

Node.js | Golang | PHP | Java | Python，并遵循README中的说明。

设置卡验证器

Virgil Card Verifier可以帮助您自动验证用户的卡签名，例如，当您从Virgil Cards服务获取卡时。

默认情况下，VirgilCardVerifier仅验证两个签名 - 卡所有者和Virgil Cards服务的签名。

使用以下代码行设置VirgilCardVerifier

use Virgil\Crypto\VirgilCrypto;
use Virgil\Sdk\Verification\VerifierCredentials;
use Virgil\Sdk\Verification\VirgilCardVerifier;
use Virgil\Sdk\Verification\Whitelist;

// initialize Crypto library
$crypto = new VirgilCrypto();

$publicKey = $crypto->importPublicKey("EXPORTED_PUBLIC_KEY");

$yourBackendVerifierCredentials = new VerifierCredentials("YOUR_BACKEND", $publicKey);

$yourBackendWhitelist = new Whitelist([$yourBackendVerifierCredentials]);

$cardVerifier = new VirgilCardVerifier($crypto, true, true, [$yourBackendWhitelist]);

设置卡管理器

本小节展示了如何设置卡管理器模块以帮助您管理用户的公钥。

使用卡管理器，您可以

指定访问令牌（JWT）提供者。
指定用于验证您的用户、您的应用服务器、Virgil服务（可选）签名的卡验证器。

使用以下代码行设置卡管理器

use Virgil\Sdk\CardManager;
use Virgil\Sdk\Verification\VirgilCardVerifier;

$cardVerifier = new VirgilCardVerifier($virgilCrypto, true, true);

// initialize cardManager and specify accessTokenProvider, cardVerifier
$cardManager = new CardManager($virgilCrypto, $accessTokenProvider, $cardVerifier);

使用示例

在开始练习使用示例之前，请确保已配置SDK。有关更多信息，请参阅配置SDK部分。

在卡服务中生成和发布Virgil卡

使用以下代码行创建包含公钥的用户卡并将其发布在Virgil Cards服务上

use Virgil\Crypto\VirgilCrypto;
use Virgil\Sdk\CardParams;

$crypto = new VirgilCrypto();

// generate a key pair
$keyPair = $crypto->generateKeyPair();

// save Alice private key into key storage
$privateKeyStorage->store($keyPair->getPrivateKey(), "Alice");

// create and publish user's card with identity Alice on the Cards Service
$card = $cardManager->publishCard(
    CardParams::create(
        [
            CardParams::PublicKey  => $keyPair->getPublicKey(),
            CardParams::PrivateKey => $keyPair->getPrivateKey(),
        ]
    )
);

签名并加密数据

Virgil Core SDK允许您使用用户的私钥和他们的Virgil卡对任何类型的数据进行签名和加密。

在以下示例中，我们从定制的密钥存储中加载私钥，并从Virgil Cards服务获取接收者的卡。接收者的卡包含公钥，我们将使用它来加密数据并验证签名。

use Virgil\Crypto\Core\VirgilKeys\VirgilPublicKeyCollection;

// prepare a message
$dataToEncrypt = 'Hello, Bob!';

// load a private key from a device storage
$alicePrivateKeyEntry = $privateKeyStorage->load('Alice');

// using cardManager search for Bob's cards on Cards Service
$cards = $cardManager->searchCards('Bob');

$bobRelevantCardsPublicKeys = array_map(
    function (Virgil\Sdk\Card $cards) {
        return $cards->getPublicKey();
    },
    $cards
);

$bobRelevantCardsPublicKeysCollection = new VirgilPublicKeyCollection($bobRelevantCardsPublicKeys);

// sign a message with a private key then encrypt using Bob's public keys
$encryptedData = $crypto->signAndEncrypt(
    $dataToEncrypt,
    $alicePrivateKeyEntry->getPrivateKey(),
    $bobRelevantCardsPublicKeysCollection
);

解密数据和验证签名

一旦用户收到已签名和加密的消息，他们可以使用自己的私钥对其进行解密，并使用发送者的卡验证签名

use Virgil\Crypto\Core\VirgilKeys\VirgilPublicKeyCollection;

// load a private key from a device storage
$bobPrivateKeyEntry = $privateKeyStorage->load('Bob');

// using cardManager search for Alice's cards on Cards Service
$cards = $cardManager->searchCards('Alice');

$aliceRelevantCardsPublicKeys = array_map(
    function (Virgil\Sdk\Card $cards) {
        return $cards->getPublicKey();
    },
    $cards
);

$aliceRelevantCardsPublicKeysCollection = new VirgilPublicKeyCollection($aliceRelevantCardsPublicKeys);

// decrypt with a private key and verify using one of Alice's public keys
$decryptedData = $crypto->decryptAndVerify(
    $encryptedData,
    $bobPrivateKeyEntry->getPrivateKey(),
    $aliceRelevantCardsPublicKeysCollection
);

通过ID获取卡

使用以下代码行通过ID从Virgil Cloud获取用户的卡

// using cardManager get a user's card from the Cards Service
$card = $cardManager->getCard("f4bf9f7fcbedaba0392f108c59d8f4a38b3838efb64877380171b54475c2ade8");

通过用户的身份获取卡

对于单个用户，使用以下代码行通过用户的identity获取用户的卡

// using cardManager search for user's cards on Cards Service
$cards = $cardManager->searchCards("Bob");

吊销卡

如果用户不再需要，您可以撤销其卡片。已撤销的卡片仍可以通过其标识符获取，但在搜索查询中不会出现。

// using cardManager revoke user's card on Cards Service by card id
$cardManager->revokeCard("f4bf9f7fcbedaba0392f108c59d8f4a38b3838efb64877380171b54475c2ade8");

使用 VirgilCrypto 生成密钥对

您可以使用以下代码生成密钥对并将其保存在安全密钥存储中：

use \Virgil\Crypto\VirgilCrypto;

$crypto = new VirgilCrypto();

$keyPair = $crypto->generateKeyPair();

从文件系统密钥存储中保存和检索密钥

use Virgil\Sdk\Storage\PrivateKeyStorage;
use Virgil\Crypto\VirgilCrypto;

$crypto = new VirgilCrypto();

$keyPair = $crypto->generateKeyPair();
$storage = new PrivateKeyStorage($crypto, '/var/www/storage');

$storage->store($keyPair->getPrivateKey(), 'alicePk');

$alicePk = $storage->load('alicePk');

文档

Virgil Security 提供了一组强大的 API，您可以通过开发者文档开始使用。

许可证

本库在3-clause BSD 许可证下发布。

支持

我们的开发者支持团队随时为您提供帮助。有关更多信息，请访问我们的帮助中心。

您可以在Twitter上找到我们，或发送电子邮件至support@VirgilSecurity.com。

此外，您还可以在我们的Slack社区中从我们的支持团队获得额外帮助。

virgil / sdk

维护者

详细信息