{"id":19198447,"url":"https://github.com/virgilsecurity/virgil-sdk-x","last_synced_at":"2025-06-17T21:34:40.368Z","repository":{"id":48053894,"uuid":"41714430","full_name":"VirgilSecurity/virgil-sdk-x","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":"2023-08-14T03:13:39.000Z","size":55708,"stargazers_count":28,"open_issues_count":1,"forks_count":5,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-05-09T01:15:00.449Z","etag":null,"topics":["carthage","cocoapods","core-sdk","cryptography","encryption","end-to-end-encryption","gdpr","hipaa","pki","sdk","swift"],"latest_commit_sha":null,"homepage":"https://virgilsecurity.com/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","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}},"created_at":"2015-09-01T03:18:50.000Z","updated_at":"2025-02-05T07:49:51.000Z","dependencies_parsed_at":"2024-01-07T22:23:43.103Z","dependency_job_id":"332fb992-9904-4ef1-b1b3-5f60e2741f90","html_url":"https://github.com/VirgilSecurity/virgil-sdk-x","commit_stats":{"total_commits":1137,"total_committers":13,"mean_commits":87.46153846153847,"dds":0.4001759014951627,"last_synced_commit":"b929188c23269af44ab848c4f72ebd95e0c36bfb"},"previous_names":["virgilsecurity/virgilkeysios","virgilsecurity/virgil-sdk-keys-x"],"tags_count":110,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-x","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-x/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-x/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-x/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VirgilSecurity","download_url":"https://codeload.github.com/VirgilSecurity/virgil-sdk-x/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253171272,"owners_count":21865297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["carthage","cocoapods","core-sdk","cryptography","encryption","end-to-end-encryption","gdpr","hipaa","pki","sdk","swift"],"created_at":"2024-11-09T12:22:03.942Z","updated_at":"2025-05-09T01:15:10.332Z","avatar_url":"https://github.com/VirgilSecurity.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Virgil Core SDK Objective-C/Swift\n\n[![Build Status](https://api.travis-ci.com/VirgilSecurity/virgil-sdk-x.svg?branch=master)](https://travis-ci.com/VirgilSecurity/virgil-sdk-x)\n[![CocoaPods Compatible](https://img.shields.io/cocoapods/v/VirgilSDK.svg)](https://cocoapods.org/pods/VirgilSDK)\n[![SPM compatible](https://img.shields.io/badge/Swift_Package_Manager-compatible-green.svg?style=flat)](https://www.swift.org/package-manager)\n[![Platform](https://img.shields.io/cocoapods/p/VirgilSDK.svg?style=flat)](https://cocoapods.org/pods/VirgilSDK)\n[![GitHub license](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg)](https://github.com/VirgilSecurity/virgil/blob/master/LICENSE)\n\n\n[Introduction](#introduction) | [SDK Features](#sdk-features) | [Installation](#installation) | [Configure SDK](#configure-sdk) | [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-x)\n\n## Installation\n\nVirgil Core SDK is provided as a set of frameworks. These frameworks are distributed via SPM and CocoaPods. In this guide you'll also find one more package - Virgil Crypto Library, that is used by the SDK to perform cryptographic operations.\n\nAll frameworks are available for:\n- iOS 11.0+\n- macOS 10.11+\n- tvOS 11.0+\n- watchOS 4.0+\n\n### COCOAPODS\n\n[CocoaPods](http://cocoapods.org) is a dependency manager for Cocoa projects. You can install it with the following command:\n\n```bash\n$ gem install cocoapods\n```\n\nTo integrate VirgilSDK into your Xcode project using CocoaPods, specify it in your *Podfile*:\n\n```bash\ntarget '\u003cYour Target Name\u003e' do\n  use_frameworks!\n\n  pod 'VirgilSDK', '~\u003e 8.0'\nend\n```\n\nThen, run the following command:\n\n```bash\n$ pod install\n```\n\n### Swift Package Manager\n\n[Swift Package Manager](https://www.swift.org/package-manager) is an official Apple tool for managing the distribution of Swift code.\n\n[The Apple documentation](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app) can be used to add frameworks to an Xcode project.\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```swift\nimport VirgilSDK\n\n// Get generated token from server-side\nlet authenticatedQueryToServerSide: ((String) -\u003e Void) -\u003e Void = { completion in\n    completion(\"eyJraWQiOiI3MGI0NDdlMzIxZj....MK7p7Ak\")\n}\n\n// Setup AccessTokenProvider\nlet accessTokenProvider = CallbackJwtProvider { tokenContext, completion in\n    authenticatedQueryToServerSide { jwtString in\n        completion(jwtString, nil)\n    }\n}\n```\n\n#### Generate JWT on Server side\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```swift\nimport VirgilSDK\nimport VirgilCrypto\n\n// initialize Crypto library\nlet cardCrypto = VirgilCardCrypto()\n\nlet yourBackendVerifierCredentials =\n    VerifierCredentials(signer: \"YOUR_BACKEND\",\n                        publicKey: Data(base64Encoded: publicKeyStr)!)\n\nlet yourBackendWhitelist =\n    try! Whitelist(verifiersCredentials: [yourBackendVerifierCredentials])\n\nlet cardVerifier = VirgilCardVerifier(cardCrypto: cardCrypto,\n                                      whitelists: [yourBackendWhitelist])\n\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```swift\n// initialize cardManager and specify accessTokenProvider, cardVerifier\nlet cardManagerParams = CardManagerParams(cardCrypto: cardCrypto,\n                                          accessTokenProvider: accessTokenProvider,\n                                          cardVerifier: cardVerifier)\n\nlet cardManager = CardManager(params: cardManagerParams)\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```swift\nimport VirgilSDK\nimport VirgilCrypto\n\n// save a private key into key storage\nlet data = try! crypto.exportPrivateKey(keyPair.privateKey)\nlet entry = try! keychainStorage.store(data: data, withName: \"Alice\", meta: nil)\n\n// publish user's card on the Cards Service\ncardManager.publishCard(privateKey: keyPair.privateKey, publicKey: keyPair.publicKey).start { result in\n    switch result {\n        // Card is created\n        case .success(let card): break\n        // Error occured\n        case .failure(let error): break\n    }\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```swift\nimport VirgilSDK\nimport VirgilCrypto\n\n// prepare a message\nlet messageToEncrypt = \"Hello, Bob!\"\nlet dataToEncrypt = messageToEncrypt.data(using: .utf8)!\n\n// prepare a user's private key\nlet alicePrivateKeyEntry = try! keychainStorage.retrieveEntry(withName: \"Alice\")\nlet alicePrivateKey = try! crypto.importPrivateKey(from: alicePrivateKeyEntry.data)\n\n// using cardManager search for user's cards on Cards Service\ncardManager.searchCards(identities: [\"Bob\"]).start { result in\n    switch result {\n    // Cards are obtained\n    case .success(let cards):\n        let bobRelevantCardsPublicKeys = cards\n            .map { $0.publicKey }\n\n        // sign a message with a private key then encrypt on a public key\n        let encryptedData = try! crypto.signAndEncrypt(dataToEncrypt,\n                                                       with: alicePrivateKey,\n                                                       for: bobRelevantCardsPublicKeys)\n\n    // Error occured\n    case .failure(let error): break\n    }\n}\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```swift\nimport VirgilSDK\nimport VirgilCrypto\n\n// prepare a user's private key\nlet bobPrivateKeyEntry = try! keychainStorage.retrieveEntry(withName: \"Bob\")\nlet bobPrivateKey = try! exporter.importPrivateKey(from: bobPrivateKeyEntry.data)\n\n// using cardManager search for user's cards on Cards Service\ncardManager.searchCards(identities: [\"Alice\"]).start { result in\n    switch result {\n    // Cards are obtained\n    case .success(let cards):\n        let aliceRelevantCardsPublicKeys = cards.map { $0.publicKey }\n\n        // decrypt with a private key and verify using a public key\n        let decryptedData = try! crypto.decryptAndVerify(encryptedData, \n                                                         with: bobPrivateKey,\n                                                         usingOneOf: aliceRelevantCardsPublicKeys)\n\n    // Error occured\n    case .failure(let error): break\n    }\n}\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```swift\nimport VirgilSDK\n\n// using cardManager get a user's card from the Cards Service\ncardManager.getCard(withId: \"f4bf9f7fcbedaba0392f108c59d8f4a38b3838efb64877380171b54475c2ade8\").start { result in\n    switch result {\n    // Card is obtained\n    case .success(let card): break\n    // Error occurred\n    case .failure(let error): break\n    }\n}\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```swift\nimport VirgilSDK\n\n// using cardManager search for user's cards on Cards Service\ncardManager.searchCards(identity: \"Bob\").start { result in\n    switch result {\n    // Cards are obtained\n    case .success(let cards): break\n    // Error occurred\n    case .failure(let error): break\n    }\n}\n```\n\n### Revoke Card\n\nYou can revoke user's Card in case they don't need it anymore. Revoked Card can still be obtained using its identifier, but this card won't appear during search query.\n\n```swift\nimport VirgilSDK\n\nlet result = cardManager.revokeCard(withId: card.identifier).start { result in\n    switch result {\n        // Card is revoked\n        case .success: break\n        // Error occured\n        case .failure(let error): break\n    }\n}\n```\n\n### Generate key pair using VirgilCrypto\n\nYou can generate a key pair and save it in a secure key storage with the following code:\n\n```swift\nimport VirgilCrypto\n\nlet crypto = try! VirgilCrypto()\n\nlet keyPair = try! crypto.generateKeyPair()\n```\n\n### Save and retrieve key using keychain storage\n\n```swift\nimport VirgilSDK\nimport VirgilCrypto\n\nlet storageParams = try! KeychainStorageParams.makeKeychainStorageParams()\nlet keychainStorage = KeychainStorage(storageParams: storageParams)\n\n// export key to Data\nlet data = try! crypto.exportPrivateKey(keyPair.privateKey)\n\nlet identity = \"Alice\"\n\n// save key data\nlet entry = try! keychainStorage.store(data: data, withName: identity, meta: nil)\n\n// retrieve key data\nlet retrievedEntry = try! keychainStorage.retrieveEntry(withName: identity)\n\n// import key from Data\nlet privateKey = try! exporter.importPrivateKey(from: retrievedEntry.data)\n```\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-x","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvirgilsecurity%2Fvirgil-sdk-x","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirgilsecurity%2Fvirgil-sdk-x/lists"}