{"id":19198479,"url":"https://github.com/virgilsecurity/virgil-sdk-python","last_synced_at":"2026-03-06T22:05:48.177Z","repository":{"id":146283387,"uuid":"50996032","full_name":"VirgilSecurity/virgil-sdk-python","owner":"VirgilSecurity","description":"Virgil Core SDK allows developers to get up and running with Virgil Cards Service API quickly and add end-to-end security to their new or existing digital solutions to become HIPAA and GDPR compliant and more.","archived":false,"fork":false,"pushed_at":"2020-04-28T10:40:23.000Z","size":16468,"stargazers_count":10,"open_issues_count":0,"forks_count":2,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-09-10T09:28:12.145Z","etag":null,"topics":["cryptography","encryption","end-to-end-encryption","gdpr","hipaa","pki","sdk"],"latest_commit_sha":null,"homepage":"https://virgilsecurity.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VirgilSecurity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-02-03T11:44:22.000Z","updated_at":"2022-02-16T18:18:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"1fe0fa1e-4e03-48e1-9b35-83c811a6f163","html_url":"https://github.com/VirgilSecurity/virgil-sdk-python","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/VirgilSecurity/virgil-sdk-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VirgilSecurity","download_url":"https://codeload.github.com/VirgilSecurity/virgil-sdk-python/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30200756,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptography","encryption","end-to-end-encryption","gdpr","hipaa","pki","sdk"],"created_at":"2024-11-09T12:22:14.488Z","updated_at":"2026-03-06T22:05:48.156Z","avatar_url":"https://github.com/VirgilSecurity.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Virgil Core SDK Python\n[![Travis (.com)](https://img.shields.io/travis/com/VirgilSecurity/virgil-sdk-python/master.svg)](https://travis-ci.com/VirgilSecurity/virgil-sdk-python) [![PyPI](https://img.shields.io/pypi/v/virgil-sdk.svg)](https://pypi.python.org/pypi/virgil-sdk) [![PyPI](https://img.shields.io/pypi/wheel/virgil-sdk.svg)](https://pypi.python.org/pypi/virgil-sdk) [![PyPI](https://img.shields.io/pypi/pyversions/virgil-sdk.svg)](https://pypi.python.org/pypi/virgil-sdk)\n\n[Introduction](#introduction) | [SDK Features](#sdk-features) | [Installation](#installation) | [Configure SDK](#configure-sdk) | [Sample Backend for JWT Generation](#sample-backend-for-jwt-generation) | [Usage Examples](#usage-examples) | [Docs](#docs) | [Support](#support)\n\n## Introduction\n\n\u003ca href=\"https://developer.virgilsecurity.com/docs\"\u003e\u003cimg width=\"230px\" src=\"https://cdn.virgilsecurity.com/assets/images/github/logos/virgil-logo-red.png\" align=\"left\" hspace=\"10\" vspace=\"6\"\u003e\u003c/a\u003e [Virgil Security](https://virgilsecurity.com) provides a set of APIs for adding security to any application. In a few simple steps you can encrypt communications, securely store data, and ensure data integrity. Virgil Security products are available for desktop, embedded (IoT), mobile, cloud, and web applications in a variety of modern programming languages.\n\nThe Virgil Core SDK is a low-level library that allows developers to get up and running with [Virgil Cards Service API](https://developer.virgilsecurity.com/docs/platform/api-reference/cards-service/) quickly and add end-to-end security to their new or existing digital solutions.\n\nIn case you need additional security functionality for multi-device support, group chats and more, try our high-level [Virgil E3Kit framework](https://github.com/VirgilSecurity/awesome-virgil#E3Kit).\n\n## SDK Features\n- Communicate with [Virgil Cards Service](https://developer.virgilsecurity.com/docs/platform/api-reference/cards-service/)\n- Manage users' public keys\n- Encrypt, sign, decrypt and verify data\n- Store private keys in secure local storage\n- Use [Virgil Crypto Library](https://github.com/VirgilSecurity/virgil-crypto-python)\n- Use your own crypto library\n\n## Installation\n\nThe Virgil Core SDK Python is provided as a package named *virgil_sdk*. The package is distributed via Pypi package management system. The package is available for:\n- Python 2.7.x\n- Python 3.x\n\n\nTo install the pip package use the command below:\n\n```bash\npip install virgil-sdk\n```\n\n\n## Configure SDK\n\nThis section contains guides on how to set up Virgil Core SDK modules for authenticating users, managing Virgil Cards and storing private keys.\n\n### Set up authentication\n\nSet up user authentication with tokens that are based on the [JSON Web Token standard](https://jwt.io/) with some Virgil modifications.\n\nIn order to make calls to Virgil Services (for example, to publish user's Card on Virgil Cards Service), you need to have a JSON Web Token (\"JWT\") that contains the user's `identity`, which is a string that uniquely identifies each user in your application.\n\nCredentials that you'll need:\n\n|Parameter|Description|\n|--- |--- |\n|App ID|ID of your Application at [Virgil Dashboard](https://dashboard.virgilsecurity.com)|\n|App Key ID|A unique string value that identifies your account at the Virgil developer portal|\n|App Key|A Private Key that is used to sign API calls to Virgil Services. For security, you will only be shown the App Key when the key is created. Don't forget to save it in a secure location for the next step|\n\n#### Set up JWT provider on Client side\n\nUse these lines of code to specify which JWT generation source you prefer to use in your project:\n\n```python\nfrom virgil_sdk.jwt.providers import CallbackJwtProvider\n\n# Get generated token from server-side\ndef get_token_from_server():\n    jwt_from_server = aunthficated_query_to_server(token_context)\n    return jwt_from_server\n\n# setup access token\naccess_token_provider = CallbackJwtProvider(get_token_from_server)\n```\n\n#### Generate JWT on Server side\n\nNext, you'll need to set up the `JwtGenerator` and generate a JWT using the Virgil SDK.\n\nHere is an example of how to generate a JWT:\n\n```python\nimport datetime\n\nfrom virgil_crypto import VirgilCrypto\nfrom virgil_crypto.access_token_signer import AccessTokenSigner\nfrom virgil_sdk.jwt import JwtGenerator\nfrom virgil_sdk.utils import Utils\n\n# App Key (you got this Key at Virgil Dashboard)\napp_key_base64 = \"MIGhMF0GCSqGSIb3DQEFDTBQMC8GCSqGS...gRbjAtoWkfWraSLD6gj0=\"\nprivate_key_data = Utils.b64_decode(app_key_base64)\n\n# Crypto library imports a private key into a necessary format\ncrypto = VirgilCrypto()\napp_key = crypto.import_private_key(private_key_data)\n\n#  initialize accessTokenSigner that signs users JWTs\naccess_token_signer = AccessTokenSigner()\n\n# use your App Credentials you got at Virgil Dashboard:\napp_id = \"be00e10e4e1f4bf58f9b4dc85d79c77a\"\napp_key_id = \"70b447e321f3a0fd\"\nttl = datetime.timedelta(hours=1).seconds\n\n# setup JWT generator with necessary parameters:\njwt_generator = JwtGenerator(app_id, app_key, app_key_id, ttl, access_token_signer)\n\n# generate JWT for a user\n# remember that you must provide each user with his unique JWT\n# each JWT contains unique user's identity (in this case - Alice)\n# identity can be any value: name, email, some id etc.\nidentity = \"Alice\"\nalice_jwt = jwt_generator.generate_token(identity)\n\n# as result you get users JWT, it looks like this: \"eyJraWQiOiI3MGI0NDdlMzIxZjNhMGZkIiwidHlwIjoiSldUIiwiYWxnIjoiVkVEUzUxMiIsImN0eSI6InZpcmdpbC1qd3Q7dj0xIn0.eyJleHAiOjE1MTg2OTg5MTcsImlzcyI6InZpcmdpbC1iZTAwZTEwZTRlMWY0YmY1OGY5YjRkYzg1ZDc5Yzc3YSIsInN1YiI6ImlkZW50aXR5LUFsaWNlIiwiaWF0IjoxNTE4NjEyNTE3fQ.MFEwDQYJYIZIAWUDBAIDBQAEQP4Yo3yjmt8WWJ5mqs3Yrqc_VzG6nBtrW2KIjP-kxiIJL_7Wv0pqty7PDbDoGhkX8CJa6UOdyn3rBWRvMK7p7Ak\"\n# you can provide users with JWT at registration or authorization steps\n# Send a JWT to client-side\njwt_string = alice_jwt.to_string()\n```\n\nFor this subsection we've created a sample backend that demonstrates how you can set up your backend to generate the JWTs. To set up and run the sample backend locally, head over to your GitHub repo of choice:\n\n[Node.js](https://github.com/VirgilSecurity/sample-backend-nodejs) | [Golang](https://github.com/VirgilSecurity/sample-backend-go) | [PHP](https://github.com/VirgilSecurity/sample-backend-php) | [Java](https://github.com/VirgilSecurity/sample-backend-java) | [Python](https://github.com/VirgilSecurity/virgil-sdk-python/tree/master#sample-backend-for-jwt-generation)\n and follow the instructions in README.\n \n### Set up Card Verifier\n\nVirgil Card Verifier helps you automatically verify signatures of a user's Card, for example when you get a Card from Virgil Cards Service.\n\nBy default, `VirgilCardVerifier` verifies only two signatures - those of a Card owner and Virgil Cards Service.\n\nSet up `VirgilCardVerifier` with the following lines of code:\n\n```python\nfrom virgil_crypto.card_crypto import CardCrypto\nfrom virgil_sdk import VirgilCardVerifier\nfrom virgil_sdk.verification import VerifierCredentials, WhiteList\n\n# initialize Crypto library\ncard_crypto = CardCrypto()\nyour_backend_verifier_credentials = VerifierCredentials(signer=\"YOUR_BACKEND\", public_key_base64=public_key_str)\n\nyour_backend_white_list = WhiteList()\nyour_backend_white_list.verifiers_credentials = your_backend_verifier_credentials\n\nverifier = VirgilCardVerifier(card_crypto, white_lists=[your_backend_white_list])\n```\n\n### Set up Card Manager\n\nThis subsection shows how to set up a Card Manager module to help you manage users' public keys.\n\nWith Card Manager you can:\n- specify an access Token (JWT) Provider.\n- specify a Card Verifier used to verify signatures of your users, your App Server, Virgil Services (optional).\n\nUse the following lines of code to set up the Card Manager:\n\n```python\nfrom virgil_sdk import CardManager, VirgilCardVerifier\n\n# initialize card_manager and specify access_token_provider, card_verifier\ncard_manager = CardManager(\n    card_crypto,\n    access_token_provider,\n    card_verifier\n)\n```\n\n### Set up Key Storage for private keys\n\nThis subsection shows how to set up a `VSSKeyStorage` using Virgil SDK in order to save private keys after their generation.\n\nHere is an example of how to set up the `VSSKeyStorage` class:\n\n```python\nfrom virgil_crypto import VirgilCrypto, PrivateKeyExporter\nfrom virgil_sdk.storage import PrivateKeyStorage\n\n# initialize Crypto library\ncrypto = VirgilCrypto()\n\n# Generate a private key\nkey_pair = crypto.generate_keys()\nprivate_key = key_pair.private_key\n\n# Setup PrivateKeyStorage\nexporter = PrivateKeyExporter()\nprivate_key_storage = PrivateKeyStorage(exporter, \"YOUR_PASSWORD\")\n\n# Store a private key with a name, for example Alice\nprivate_key_storage.store(private_key, \"Alice\")\n\n# To load Alice private key use the following code lines:\nloaded_private_key, loaded_additional_data = private_key_storage.load(\"Alice\")\n\n# Delete a private key\nprivate_key_storage.delete(\"Alice\")\n```\n\n## Sample Backend for JWT Generation\n\nIn order to configure the SDK you can use the sample backend for generating JWT which we created for you.\n**JWT** is a unique string that is used by Virgil to authenticate you and users of your application on Virgil Services.\n\n\u003e Do not use this authentication in production. Requests to a /virgil-jwt endpoint must be allowed for authenticated users. Use your application authorization strategy.\n\n### Clone repository\n\nClone the repository from GitHub.\n\n```\n$ git clone https://github.com/VirgilSecurity/virgil-sdk-python.git\n```\n\n### Get Virgil credentials\n\nIf you don't have an account yet, [sign up for one](https://dashboard.virgilsecurity.com/signup) using your e-mail.\n\nTo generate a JWT the following values are required:\n\n| Variable Name                     | Description                    |\n|-----------------------------------|--------------------------------|\n| API_PRIVATE_KEY                  | Private key of your API key that is used to sign the JWTs. |\n| API_KEY_ID               | ID of your API key. A unique string value that identifies your account in the Virgil Cloud. |\n| APP_ID                   | ID of your Virgil Application. |\n\n### Add Virgil credentials to sample_backend_for_jwt_generation.py\n\n- navigate to `/examples/sample_backend_for_jwt_generation.py`\n- fill it with your account credentials (`# FILL THIS FIELD`)\n- save the file\n\n### Run the server\n\nIt is required to have Flask installed in order to start the server. In cmd, run the following command:\n\n```\n$ pip install Flask\n```\n\nNow, start the server:\n\n```\n$ cd examples/\n$ python sample_backend_for_jwt_generation.py\n```\n\nAfter that use your client code to make a request to get a JWT from the sample backend that is working on http://localhost:5000.\n\n### Specification\n\n#### /authenticate endpoint\nThis endpoint is an example of users authentication. It takes user `identity` and responds with unique token.\n\n```http\nPOST https://localhost:5000/authenticate HTTP/1.1\nContent-type: application/json;\n\n{\n    \"identity\": \"string\"\n}\n\nResponse:\n\n{\n    \"auth_token\": \"string\"\n}\n```\n\n#### /virgil-jwt endpoint\nThis endpoint checks whether a user is authorized by an authorization header. It takes user's `auth_token`, finds related user identity and generates a `virgil_token` (which is [JSON Web Token](https://jwt.io/)) with this `identity` in a payload. Use this token to make authorized api calls to Virgil Cloud.\n\n```http\nGET https://localhost:5000/virgil-jwt HTTP/1.1\nContent-type: application/json;\nAuthorization: Bearer \u003cauthToken\u003e\n\nResponse:\n\n{\n    \"virgil_token\": \"string\"\n}\n```\n\n#### Virgil JWT generation\nTo generate JWT, you need to use the `JwtGenerator` class from the SDK. You can use the `generate_jwt` function from the `sample_backend_for_jwt_generation.py` which will return the JWT with the user's identity.\n\n\n## Usage Examples\n\nBefore you start practicing with the usage examples, make sure that the SDK is configured. See the [Configure SDK](#configure-sdk) section for more information.\n\n### Generate and publish Virgil Cards at Cards Service\n\nUse the following lines of code to create a user's Card with a public key inside and publish it at Virgil Cards Service:\n\n```python\nfrom virgil_crypto import VirgilCrypto\nfrom virgil_sdk.storage import PrivateKeyStorage\n\ncrypto = VirgilCrypto()\n\n# generate a key pair\nkey_pair = crypto.generate_keys()\n\n# save Alice private key into key sotrage\nprivate_key_storage = PrivateKeyStorage()\nprivate_key_storage.store(key_pair.private_key, \"Alice\")\n\n# create and publish user's card with identity Alice on the Card Service\ncard = card_manager.publish_card(\n    identity=\"Alice\",\n    private_key=key_pair.private_key,\n    public_key=key_pair.public_key\n)\n```\n\n### Sign then encrypt data\n\nVirgil Core SDK allows you to use a user's private key and their Virgil Cards to sign and encrypt any kind of data.\n\nIn the following example, we load a private key from a customized key storage and get recipient's Card from the Virgil Cards Service. Recipient's Card contains a public key which we will use to encrypt the data and verify a signature.\n\n```python\nfrom virgil_sdk.utils import Utils\n\n# prepare a message\nmessage_to_encrypt = \"Hello, Bob!\"\ndata_to_encrypt = Utils.strtobytes(message_to_encrypt)\n\n# load a private key from a device storage\nalice_private_key, alice_private_key_additional_data = private_key_storage.load(\"Alice\")\n\n# using CardManager search for Bob's cards on Cards Service\ncards = card_manager.search_card(\"Bob\")\nbob_relevant_public_keys = list(map(lambda x: x.public_key, cards))\n\n# sign a message with a private key then encrypt using Bob's public keys\nencrypted_data = crypto.sign_then_encrypt(data_to_encrypt, alice_private_key, bob_relevant_public_keys)\n```\n\n### Decrypt data and verify signature\n\nOnce the user receives the signed and encrypted message, they can decrypt it with their own private key and verify the signature with the sender's Card:\n\n```python\n\n# load private key from device storage\nbob_private_key, bob_private_key_additional_data = private_key_storage.load(\"Bob\")\n\n# using CardManager search for Alice's cards on Cards Service\ncards = card_manager.search_card(\"Alice\")\nalice_relevant_public_keys = list(map(lambda x: x.public_key, cards))\n\n# decrypt with a private key and verify using one of Alice's public keys\ndecrypted_data = crypto.decrypt_then_verify(encrypted_data, bob_private_key, alice_relevant_public_keys)\n```\n\n### Get Card by its ID\n\nUse the following lines of code to get a user's card from Virgil Cloud by its ID:\n\n```python\n\n# using CardManager get a user's card from the Cards Service\ncard = card_manager.get_card(\"f4bf9f7fcbedaba0392f108c59d8f4a38b3838efb64877380171b54475c2ade8\")\n```\n\n### Get Card by user's identity\n\nFor a single user, use the following lines of code to get a user's Card by a user's `identity`:\n\n```python\n# using CardManager search for user's cards on Cards Service\ncard = card_manager.search_card(\"Bob\")\n```\n\n### Encrypt and decrypt large file\n\nIf you need to encrypt files larger than 50 MB, we recommend you to take a look at the full code example of how to encrypt and decrypt large files without causing RAM usage overrun [here](/examples/encrypt_decrypt_large_file.py).\n\n## Docs\n\nVirgil Security has a powerful set of APIs, and the [Developer Documentation](https://developer.virgilsecurity.com/) can get you started today.\n\n## License\n\nThis library is released under the [3-clause BSD License](LICENSE).\n\n## Support\n\nOur developer support team is here to help you. Find out more information on our [Help Center](https://help.virgilsecurity.com/).\n\nYou can find us on [Twitter](https://twitter.com/VirgilSecurity) or send us email support@VirgilSecurity.com.\n\nAlso, get extra help from our support team on [Slack](https://virgilsecurity.com/join-community).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirgilsecurity%2Fvirgil-sdk-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvirgilsecurity%2Fvirgil-sdk-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirgilsecurity%2Fvirgil-sdk-python/lists"}