Class: Virgil::SDK::HighLevel::VirgilCardManager

Inherits:
Object
  • Object
show all
Defined in:
lib/virgil/sdk/high_level/virgil_card_manager.rb

Overview

This class provides a list of methods to manage the VirgilCard entities.

Defined Under Namespace

Classes: AccessTokenException, AppCredentialsException, CardArray

Instance Method Summary collapse

Constructor Details

#initialize(context) ⇒ VirgilCardManager

Initializes a new instance of the Virgil::SDK::HighLevel::VirgilCardManager class.



48
49
50
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 48

def initialize(context)
  @context = context
end

Instance Method Details

#create(identity, owner_key, custom_data = {}) ⇒ VirgilCard

Creates a new Virgil Card that is representing user's Public key and information.

Examples:

virgil = VirgilApi.new(access_token: "[YOUR_ACCESS_TOKEN_HERE]")
alice_key = virgil.keys.generate()
alice_card = virgil.cards.create("alice", alice_key)
# DEVELOPERS HAVE TO EXPORT AND THEN TRANSMIT THE VIRGIL CARD TO THE APP'S SERVER SIDE WHERE IT WILL
# BE SIGNED, VALIDATED AND THEN PUBLISHED ON VIRGIL SERVICES (THIS IS NECESSARY FOR
# FURTHER OPERATIONS WITH THE VIRGIL CARD).

Parameters:

  • identity (String) —

    The user's identity.

  • owner_key (VirgilKey) —

    The owner's Virgil key.

  • custom_data (Hash) (defaults to: {}) —

    is an associative array that contains application specific parameters(under key :data) and information about the device on which the keypair was created(under key :device and :device_name). example: {my_key1: “my_val1”, my_key2: “my_val2”, device: “iPhone6s”, device_name: “Space grey one”}.

Returns:

  • (VirgilCard) —

    Created unpublished Virgil Card that is representing user's Public key.

See Also:



133
134
135
136
137
138
139
140
141
142
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 133

def create(identity, owner_key, custom_data={})
  card = context.client.new_card(
      identity,
      VirgilIdentity::UNKNOWN,
      owner_key.private_key,
      custom_data
  )

  VirgilCard.new(context: context, card: card)
end

#create_global(identity:, identity_type:, owner_key:, custom_data: {}) ⇒ VirgilCard

Creates a new Global Virgil Card that is representing user's Public key and information.

Examples:

virgil = VirgilApi.new
alice_key = virgil.keys.generate()
# save the Virgil Key into storage
alice_key.save("[KEY_NAME]", "[KEY_PASSWORD]")
# create a global Virgil Card
alice_global_card = virgil.cards.create_global(
    identity: "alice@virgilsecurity.com",
    identity_type: VirgilIdentity::EMAIL,
    owner_key: alice_key
)

Parameters:

  • identity (String) —

    The user's identity.

  • identity_type (String) —

    it can be VirgilIdentity::EMAIL or VirgilIdentity::APPLICATION.

  • owner_key (VirgilKey) —

    The owner's Virgil key.

  • custom_data (Hash) —

    is an associative array that contains application specific parameters(under key :data) and information about the device on which the keypair was created(under key :device and :device_name). example: {my_key1: “my_val1”, my_key2: “my_val2”, device: “iPhone6s”, device_name: “Space grey one”}.

Returns:

  • (VirgilCard) —

    Created unpublished Global Virgil Card that is representing user's Public key.



165
166
167
168
169
170
171
172
173
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 165

def create_global(identity:, identity_type:, owner_key:, custom_data: {})
  card = context.client.new_global_card(
      identity,
      identity_type,
      owner_key.private_key,
      custom_data
  )
  VirgilCard.new(context: context, card: card)
end

#find(*identities) ⇒ Array<VirgilCard>

Find Virgil cards by specified identities in application scope.

Examples:

virgil = VirgilApi.new(access_token: "[YOUR_ACCESS_TOKEN_HERE]")
alice_cards = virgil.cards.find("alice")

Parameters:

  • *identities (Array<String>) —

    the list of identities.

Returns:

  • (Array<VirgilCard>) —

    A list of found Virgil cards.

Raises:

  • (VirgilClient::InvalidCardException) —

    if client has validator and retrieved card signatures are not valid.

  • (AccessTokenException) —

    if access token is empty.



242
243
244
245
246
247
248
249
250
251
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 242

def find(*identities)

  raise AccessTokenException unless (context && context.access_token)

  validate_identities_param(identities)

  cards = context.client.search_cards_by_identities(*identities)
  virgil_cards = cards.map { |v| VirgilCard.new(context: context, card: v) }
  CardArray.new(virgil_cards)
end

#find_global(identity_type, *identities) ⇒ Array<VirgilCard>

Find Global Virgil cards by specified identity type and identities.

Examples:

virgil = VirgilApi.new()
alice_global_cards = virgil.cards.find_global("alice")
# search for all Global Virgil Cards
bob_global_cards = virgil.cards.find_global(VirgilIdentity::EMAIL,
                                            "bob@virgilsecurity.com")
# search for Application Virgil Card
app_cards = virgil.cards.find_global(VirgilIdentity::APPLICATION, "com.username.appname")

Parameters:

  • identity_type (String) —

    it can be VirgilIdentity::EMAIL or VirgilIdentity::APPLICATION.

  • *identities (Array<String>) —

    the list of identities.

Returns:

  • (Array<VirgilCard>) —

    A list of found Global Virgil cards.

Raises:

  • (VirgilClient::InvalidCardException) —

    if client has validator and retrieved card signatures are not valid.



268
269
270
271
272
273
274
275
276
277
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 268

def find_global(identity_type, *identities)

  validate_identities_param(identities)

  cards = context.client.search_cards_by_criteria(
      Client::SearchCriteria.new(identities, identity_type, Client::Card::GLOBAL)
  )
  virgil_global_cards = cards.map { |v| VirgilCard.new(context: context, card: v) }
  CardArray.new(virgil_global_cards)
end

#get(card_id) ⇒ VirgilCard

Get a card from Virgil Security services by specified Card ID.

Examples:

virgil = VirgilApi.new(access_token: "[YOUR_ACCESS_TOKEN_HERE]")
alice_card = virgil.cards.get("[USER_CARD_ID_HERE]")

Parameters:

  • card_id (String) —

    unique string that identifies the Card within Virgil Security services.

Returns:

  • (VirgilCard) —

    Found card from server response.

Raises:

  • (VirgilClient::InvalidCardException) —

    if client has validator and retrieved card signatures are not valid.



228
229
230
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 228

def get(card_id)
  VirgilCard.new(context: context, card: context.client.get_card(card_id))
end

#import(exported_card) ⇒ VirgilCard

Create new Card from base64-encoded json representation of card's content_snapshot and meta.

Examples:

virgil = VirgilApi.new(context: VirgilContext.new(
    access_token: "[YOUR_ACCESS_TOKEN_HERE]",
    credentials: VirgilAppCredentials.new(
        app_id: "[YOUR_APP_ID_HERE]",
        app_key_data: VirgilBuffer.from_file("[YOUR_APP_KEY_PATH_HERE]"),
        app_key_password: "[YOUR_APP_KEY_PASSWORD_HERE]"))
)
alice_card = virgil.cards.import(exported_alice_card)

Parameters:

  • exported_card (String) —

    base64-encoded json representation of card.

Returns:

  • (VirgilCard) —

    Virgil Card restored from snapshot.

See Also:



354
355
356
357
358
359
360
361
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 354

def import(exported_card)
  request = Client::Requests::CreateCardRequest.import(exported_card)

  VirgilCard.new(
      context: self.context,
      card: Client::Card.from_request_model(request.request_model)
  )
end

#publish(card) ⇒ Object

Publish synchronously a card into application Virgil Services scope.

Examples:

virgil = VirgilApi.new(context: VirgilContext.new(
    access_token: "[YOUR_ACCESS_TOKEN_HERE]",
    credentials: VirgilAppCredentials.new(
        app_id: "[YOUR_APP_ID_HERE]",
        app_key_data: VirgilBuffer.from_file("[YOUR_APP_KEY_PATH_HERE]"),
        app_key_password: "[YOUR_APP_KEY_PASSWORD_HERE]"))
)
virgil.cards.publish(alice_card)

Parameters:

Raises:

See Also:



191
192
193
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 191

def publish(card)
  card.publish
end

#publish_global(card, validation_token) ⇒ Object

Publish a global card into application Virgil Services scope.

Examples:

# initiate identity verification process
attempt = alice_global_card.check_identity
# After that user receives a confirmation code by email
# confirm an identity and grab the validation token
token = attempt.confirm(VirgilIdentity::EmailConfirmation.new("[CONFIRMATION_CODE]"))

# publish the Virgil Card
virgil.cards.publish_global(alice_global_card, token)

Parameters:

  • card (VirgilCard) —

    the global card to be published.

Raises:

See Also:



215
216
217
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 215

def publish_global(card, validation_token)
  card.publish_as_global(validation_token)
end

#revoke(card) ⇒ Object

Revoke a card from Virgil Services.

Parameters:

Raises:

  • (Client::HTTP::BaseConnection::ApiError) —

    if the card was not published or application credentials are not valid.

  • (AppCredentialsException) —

    if application credentials are missing. virgil = VirgilApi.new(context: VirgilContext.new(

    access_token: "[YOUR_ACCESS_TOKEN_HERE]",
credentials: VirgilAppCredentials.new(
    app_id: "[YOUR_APP_ID_HERE]",
    app_key_data: VirgilBuffer.from_file("[YOUR_APP_KEY_PATH_HERE]"),
    app_key_password: "[YOUR_APP_KEY_PASSWORD_HERE]"))

    ) # get a Virgil Card by ID alice_card = virgil.cards.get(“”)

    # revoke a Virgil Card virgil.cards.revoke(alice_card)

See Also:



298
299
300
301
302
303
304
305
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 298

def revoke(card)
  validate_app_credentials

  context.client.revoke_card(
      card.id,
      context.credentials.app_id,
      context.credentials.app_key(context.crypto))
end

#revoke_global(global_card, key_pair, validation_token) ⇒ Object

Revoke a Global card from Virgil Services.

Examples:

virgil = VirgilApi.new
# load a Virgil Key from storage
alice_key = virgil.keys.load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

# load a Virgil Card from Virgil Services
alice_global_card = virgil.cards.get("[USER_CARD_ID_HERE]")

# initiate an identity verification process.
attempt = alice_global_card.check_identity()

# grab a validation token
token = attempt.confirm(VirgilIdentity::EmailConfirmation.new("[CONFIRMATION_CODE]"))

# revoke a global Virgil Card
virgil.cards.revoke_global(alice_global_card, alice_key, token)

Parameters:

Raises:

See Also:



335
336
337
338
 
# File 'lib/virgil/sdk/high_level/virgil_card_manager.rb', line 335

def revoke_global(global_card, key_pair, validation_token)
  context.client.revoke_global_card(global_card.id, key_pair, validation_token)

end