873ba0f8bb | ||
---|---|---|
.github | ||
Submodules | ||
VCCrypto | ||
VCEntities | ||
VCNetworking | ||
VCSamples | ||
VCServices | ||
VCToken | ||
sdk.xcworkspace | ||
.gitignore | ||
.gitmodules | ||
CODE_OF_CONDUCT.md | ||
CONTRIBUTING.md | ||
LICENSE | ||
PULL_REQUEST_TEMPLATE.md | ||
README.md | ||
SECURITY.md |
README.md
This SDK is used in the Microsoft Authenticator app in order to interact with verifiable credentials and Decentralized Identifiers (DIDs) on the ION network. It can be integrated with any app to provide interactions using verifiable credentials.
Verifiable Credentials
Verifiable credentials is a W3C standard that can be used to validate information about people, organizations, and more. Verifiable credentials put people in control of their personal information, enabling more trustworthy digital experiences while respecting people's privacy.
To learn more about verifiable credentials, please review our documentation.
How to use SDK
Initializing SDK
VerifiableCredentialSDK
- this class is used to initialize the SDK. You may want to call during your dependency injection initialization:
/// Both parameters are optional:
/// - logConsumer: conforms to the VCLogConsumer to inject logging into the SDK.
/// - accessGroupIdentifier: String to tell the SDK where to save keys in KeyChain. If nil, will use the default access group.
/// Returns: Result<VCSDKStatus, Error>
let result = VerifiableCredentialSDK.initialize(logConsumer: sdkLogConsumer, accessGroupIdentifier: accessGroupIdentifier);
switch result {
case .success(let status):
print("\(status) will equal success or new master identifier created")
case .failure(let error):
print("Initialization failed because of specific error")
}
We currently support the following services:
IssuanceService()
PresentationService()
APIs
Our APIs use PromiseKit. Read more about promises here.
All our public APIs return Promise<T>
objects. This forces explicit error handling.
You can unpack and handle these promises easily in Swift with the done
and catch
statements
functionThatReturnPromise().done { objectReturned in
handleRequestSuccess(objectReturned) // will be smartcasted into <T>
}.catch { error in
handleRequestFailure(error)
}
Receive a Verifiable Credential (IssuanceService)
To receive a verifiable credential you need a service endpoint providing an issuance contract. You can either get it from someone or create your own. See How to customize your credentials for more information or use an existing provider. In the future, we plan to support the DIF standard Credential Manifest.
func issuanceSample() {
/// set up issuance service through dependency injection if you like.
let issuanceService = IssuanceService()
issuanceService.getRequest(usingUrl: "<issuance request url>").done { issuanceRequest in
self.handle(successfulRequest: issuanceRequest, with: issuanceService)
}.catch { error in
self.handle(failedRequest: error)
}
}
private func handle(successfulRequest request: IssuanceRequest, with service: IssuanceService) {
let response: IssuanceResponseContainer
do {
response = try IssuanceResponseContainer(from: request.content, contractUri: "<issuance request url>")
} catch {
VCSDKLog.sharedInstance.logError(message: "Unable to create IssuanceResponseContainer.")
return
}
service.send(response: response).done { verifiableCredential in
self.handle(successfulResponse: verifiableCredential)
}.catch { error in
self.handle(failedResponse: error)
}
}
Most issuance requests will ask you for attestations that the user might need to provide. Provide them by filling the values for the existing keys in the three available maps for self attested claims, idtokens and vcs.
private func addRequestedData(response: IssuanceResponseContainer) {
response.requestedSelfAttestedClaimMap["key string found in contract"] = "user specified values"
response.requestedIdTokenMap["configuration uri"] = "your idToken"
response.requestedVCMap["credential type"] = yourVc
}
See the full sample.
Present Verifiable Credentials (PresentationService)
A presentation request can ask for multiple VCs and follows the Presentation Exchange of the Decentralized Identity Foundation. In code, presenting follows an almost identical pattern as issuance.
func presentationSample() {
/// set up presentation service through dependency injection if you like.
let presentationService = PresentationService()
presentationService.getRequest(usingUrl: "<presentation request url>").done { presentationRequest in
self.handle(successfulRequest: presentationRequest, with: presentationService)
}.catch { error in
self.handle(failedRequest: error)
}
}
private func handle(successfulRequest request: PresentationRequest, with service: PresentationService) {
let response: PresentationResponseContainer
do {
response = try PresentationResponseContainer(from: request)
} catch {
VCSDKLog.sharedInstance.logError(message: "Unable to create PresentationResponseContainer.")
return
}
service.send(response: response).done { _ in
self.handleSuccessfulResponse()
}.catch { error in
self.handle(failedResponse: error)
}
}
You can only present VCs in a presentation request. Add the requested VCs:
private func addRequestedData(response: PresentationResponseContainer) {
response.requestedVCMap["credential type"] = yourVc
}
See the full sample.
Pairwise Identifiers
By default every relationship to relying parties (RP) will use a different DID per Relying Party such that they can not correlate users actions. The client will automatically fetch exchanged VCs from the original issuer. This behavior can be disabled on a per call basis with the isPairwise
flag in send
.
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.