virgil

package module
v4.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 15, 2018 License: BSD-3-Clause, BSD-3-Clause Imports: 18 Imported by: 19

README

Virgil Security Go SDK

Installation | Initialization | Encryption / Decryption Example | Documentation | Support

Virgil Security provides a set of APIs for adding security to any application. In a few steps you can encrypt communication, securely store data, provide passwordless authentication, and ensure data integrity.

To initialize and use Virgil SDK, you need to have Developer Account.

Installation

The package is available for Go 1.7.1 and newer.

Installing the package using Package Manager Console

go get -u gopkg.in/virgil.v4

Initialization

Be sure that you have already registered at the Dev Portal and created your application.

To initialize the SDK at the Client Side you need only the Access Token created for a client at Dev Portal. The Access Token helps to authenticate client's requests.

api, err := virgilapi.New("[YOUR_ACCESS_TOKEN_HERE]")

To initialize the SDK at the Server Side you need the application credentials (Access Token, App ID, App Key and App Key Password) you got during Application registration at the Dev Portal.

keyfile, err := ioutil.ReadFile("[YOUR_APP_KEY_FILEPATH_HERE]")

api, err := virgilapi.NewWithConfig(virgilapi.Config{
        Token: "[YOUR_ACCESS_TOKEN_HERE]",
        Credentials: &virgilapi.AppCredentials{
            AppId: "[YOUR_APP_ID_HERE]",
            PrivateKey: keyfile,
            PrivateKeyPassword : "[YOUR_APP_KEY_PASSWORD_HERE]",
        },
    })

Encryption / Decryption Example

Virgil Security simplifies adding encryption to any application. With our SDK you may create unique Virgil Cards for your all users and devices. With users' Virgil Cards, you can easily encrypt any data at Client Side.

// find Alice's Virgil Card(s) at Virgil Services
aliceCards, err := api.Cards.Find("alice")

// encrypt the message using Alice's Virgil Cards
message := virgilapi.BufferFromString("Hello Alice!")
cipherData, err := aliceCards.Encrypt(message)

//transmit the message using your preferred technology to Alice
transmit(cipherData.ToBase64String())

Alice uses her Virgil Private Key to decrypt the encrypted message.

// load Alice's Virgil Key from secure storage provided by default.
aliceKey, err := api.Keys.Load("alice_key_1", "mypassword")

// get buffer from base64 encoded string
encryptedData, err := virgilapi.BufferFromBase64String(transferData)

// decrypt message using Alice's Virgil key.
originalData, err := aliceKey.Decrypt(encryptedData)

// originalData = aliceKey.Decrypt(encryptedData)
originalMessage := originalData.ToString()

Next: On the page below you can find configuration documentation and the list of our guides and use cases where you can see appliance of Virgil Go SDK.

Documentation

Virgil Security has a powerful set of APIs and the documentation to help you get started:

License

This library is released under the 3-clause BSD License.

Support

Our developer support team is here to help you. You can find us on Twitter and email.

Documentation

Overview

Package virgil is the pure Go implementation of Virgil Security compatible SDK Right now it supports only ed25519 keys and signatures and curve25519 key exchange As for symmetric crypto, it's AES256-GCM Hashes used are SHA-384 for signature and SHA-256 for fingerprints

Index

Constants

This section is empty.

Variables

View Source
var (
	CardScope struct {
		Application, Global Enum
	}
	RevocationReason struct {
		Unspecified, Compromised Enum
	}
)
View Source
var (
	ErrorKeyAlreadyExists = errors.New("Key already exists")
	ErrorKeyNotFound      = errors.New("Key not found")
)
View Source
var (
	ErrNotFound = transport.ErrNotFound
)

Functions

func ClientCardsValidator

func ClientCardsValidator(validator CardsValidator) func(*Client)

ClientCardsValidator sets custom card validaor for a Virgil client

func ClientTransport

func ClientTransport(transportClient transport.Client) func(*Client)

ClientTransport sets card service protocol for a Virgil client

func Crypto

func Crypto() virgilcrypto.Crypto

Crypto returns a new instance of virgilcrypto with a default cipher

Types

type Card

type Card struct {
	ID           string
	Snapshot     []byte
	Identity     string
	IdentityType string
	PublicKey    virgilcrypto.PublicKey
	Scope        Enum
	Data         map[string]string
	DeviceInfo   DeviceInfo
	CreatedAt    string
	CardVersion  string
	Signatures   map[string][]byte
	Relations    map[string][]byte
}

Card is basically a public key + meta information like identity, its type and so on The ID of a card is the hash of its Snapshot (json encoded basic fields)

func (*Card) Encrypt

func (c *Card) Encrypt(data []byte) ([]byte, error)

Encrypt encrypts data for a given card using ECIES

func (*Card) SignThenEncrypt

func (c *Card) SignThenEncrypt(data []byte, signerKey virgilcrypto.PrivateKey) ([]byte, error)

SignThenEncrypt encrypts data for a given card using ECIES and signs the plaintext

func (*Card) ToRequest

func (c *Card) ToRequest() (*SignableRequest, error)

func (*Card) Verify

func (c *Card) Verify(data, signature []byte) (bool, error)

Verify verifies a signature of data using the provided Card. Must return non nil error when the result is false

type CardModel

type CardModel struct {
	Identity     string            `json:"identity"`
	IdentityType string            `json:"identity_type"`
	PublicKey    []byte            `json:"public_key"` //DER encoded public key
	Scope        Enum              `json:"scope"`
	Data         map[string]string `json:"data,omitempty"`
	DeviceInfo   DeviceInfo        `json:"info"`
}

func (*CardModel) MarshalJSON

func (mj *CardModel) MarshalJSON() ([]byte, error)

func (*CardModel) MarshalJSONBuf

func (mj *CardModel) MarshalJSONBuf(buf fflib.EncodingBuffer) error

func (*CardModel) UnmarshalJSON

func (uj *CardModel) UnmarshalJSON(input []byte) error

func (*CardModel) UnmarshalJSONFFLexer

func (uj *CardModel) UnmarshalJSONFFLexer(fs *fflib.FFLexer, state fflib.FFParseState) error

type CardParams

type CardParams struct {
	Scope      Enum
	Data       map[string]string
	DeviceInfo DeviceInfo
}

ffjson: skip

type CardResponse

type CardResponse struct {
	ID       string       `json:"id"`
	Snapshot []byte       `json:"content_snapshot"`
	Meta     ResponseMeta `json:"meta"`
}

func (*CardResponse) MarshalJSON

func (mj *CardResponse) MarshalJSON() ([]byte, error)

func (*CardResponse) MarshalJSONBuf

func (mj *CardResponse) MarshalJSONBuf(buf fflib.EncodingBuffer) error

func (*CardResponse) ToCard

func (r *CardResponse) ToCard() (*Card, error)

func (*CardResponse) UnmarshalJSON

func (uj *CardResponse) UnmarshalJSON(input []byte) error

func (*CardResponse) UnmarshalJSONFFLexer

func (uj *CardResponse) UnmarshalJSONFFLexer(fs *fflib.FFLexer, state fflib.FFParseState) error

type CardsValidator

type CardsValidator interface {
	//if the result is false then error must not be nil
	Validate(card *Card) (bool, error)
}

A CardsValidator validate response from server Validator check that a card was signed by all services

type Client

type Client struct {
	// contains filtered or unexported fields
}

A Client manages communication with Virgil Security API.

func NewClient

func NewClient(accessToken string, opts ...func(*Client)) (*Client, error)

NewClient create a new instance of Virgil client

func (*Client) AddRelation

func (c *Client) AddRelation(request *SignableRequest) (*Card, error)

AddRelation adds signature of the card signer trusts

func (*Client) ConfirmIdentity

func (c *Client) ConfirmIdentity(request *ConfirmRequest) (*ConfirmResponse, error)

func (*Client) CreateCard

func (c *Client) CreateCard(request *SignableRequest) (*Card, error)

CreateCard posts card create request to server where it checks signatures and adds it

func (*Client) DeleteRelation

func (c *Client) DeleteRelation(request *SignableRequest) (*Card, error)

AddRelation adds signature of the card signer trusts

func (*Client) GetCard

func (c *Client) GetCard(id string) (*Card, error)

GetCard return a card from Virgil Read Only Card service

func (*Client) RevokeCard

func (c *Client) RevokeCard(request *SignableRequest) error

RevokeCard deletes card from server

func (*Client) SearchCards

func (c *Client) SearchCards(criteria *Criteria) ([]*Card, error)

func (*Client) ValidateIdentity

func (c *Client) ValidateIdentity(request *ValidateRequest) error

func (*Client) VerifyIdentity

func (c *Client) VerifyIdentity(request *VerifyRequest) (*VerifyResponse, error)

type ConfirmRequest

type ConfirmRequest struct {
	ConfirmationCode string                `json:"confirmation_code"`
	ActionId         string                `json:"action_id"`
	Params           ValidationTokenParams `json:"token"`
}

type ConfirmResponse

type ConfirmResponse struct {
	Type            string `json:"type"`
	Value           string `json:"value"`
	ValidationToken string `json:"validation_token"`
}

type Criteria

type Criteria struct {
	Scope        Enum     `json:"scope,omitempty"`
	IdentityType string   `json:"identity_type,omitempty"`
	Identities   []string `json:"identities"`
}

func SearchCriteriaByAppBundle

func SearchCriteriaByAppBundle(bundle ...string) *Criteria

SearchCriteriaByAppBundle create search criteria by bundle name in global scope

func SearchCriteriaByIdentities

func SearchCriteriaByIdentities(identites ...string) *Criteria

SearchCriteriaByIdentities create search criteria by identities in application scope

type DeviceInfo

type DeviceInfo struct {
	Device     string `json:"device"`
	DeviceName string `json:"device_name"`
}

DeviceInfo is for device type & its concrete name, for example model

type Enum

type Enum string

type FileStorage

type FileStorage struct {
	RootDir string
}

func (*FileStorage) Delete

func (s *FileStorage) Delete(name string) error

func (*FileStorage) Exists

func (s *FileStorage) Exists(name string) bool

func (*FileStorage) Load

func (s *FileStorage) Load(name string) (*StorageItem, error)

func (*FileStorage) Store

func (s *FileStorage) Store(key *StorageItem) error

type KeyStorage

type KeyStorage interface {
	Store(key *StorageItem) error
	Load(name string) (*StorageItem, error)
	Exists(name string) bool
	Delete(name string) error
}

type RequestMeta

type RequestMeta struct {
	Signatures map[string][]byte `json:"signs"`
	Validation *ValidationInfo   `json:"validation,omitempty"`
}

func (*RequestMeta) MarshalJSON

func (mj *RequestMeta) MarshalJSON() ([]byte, error)

func (*RequestMeta) MarshalJSONBuf

func (mj *RequestMeta) MarshalJSONBuf(buf fflib.EncodingBuffer) error

func (*RequestMeta) UnmarshalJSON

func (uj *RequestMeta) UnmarshalJSON(input []byte) error

func (*RequestMeta) UnmarshalJSONFFLexer

func (uj *RequestMeta) UnmarshalJSONFFLexer(fs *fflib.FFLexer, state fflib.FFParseState) error

type RequestSigner

type RequestSigner struct {
}

func (*RequestSigner) AuthoritySign

func (rs *RequestSigner) AuthoritySign(req *SignableRequest, cardId string, privateKey virgilcrypto.PrivateKey) error

func (*RequestSigner) SelfSign

func (rs *RequestSigner) SelfSign(req *SignableRequest, privateKey virgilcrypto.PrivateKey) error

type ResponseMeta

type ResponseMeta struct {
	CreatedAt   string            `json:"created_at"`
	CardVersion string            `json:"card_version"`
	Signatures  map[string][]byte `json:"signs"`
	Relations   map[string][]byte `json:"relations"`
}

func (*ResponseMeta) MarshalJSON

func (mj *ResponseMeta) MarshalJSON() ([]byte, error)

func (*ResponseMeta) MarshalJSONBuf

func (mj *ResponseMeta) MarshalJSONBuf(buf fflib.EncodingBuffer) error

func (*ResponseMeta) UnmarshalJSON

func (uj *ResponseMeta) UnmarshalJSON(input []byte) error

func (*ResponseMeta) UnmarshalJSONFFLexer

func (uj *ResponseMeta) UnmarshalJSONFFLexer(fs *fflib.FFLexer, state fflib.FFParseState) error

type RevokeCardRequest

type RevokeCardRequest struct {
	ID               string `json:"card_id"`
	RevocationReason Enum   `json:"revocation_reason"`
}

func (*RevokeCardRequest) MarshalJSON

func (mj *RevokeCardRequest) MarshalJSON() ([]byte, error)

func (*RevokeCardRequest) MarshalJSONBuf

func (mj *RevokeCardRequest) MarshalJSONBuf(buf fflib.EncodingBuffer) error

func (*RevokeCardRequest) UnmarshalJSON

func (uj *RevokeCardRequest) UnmarshalJSON(input []byte) error

func (*RevokeCardRequest) UnmarshalJSONFFLexer

func (uj *RevokeCardRequest) UnmarshalJSONFFLexer(fs *fflib.FFLexer, state fflib.FFParseState) error

type SignableRequest

type SignableRequest struct {
	Snapshot []byte      `json:"content_snapshot"`
	Meta     RequestMeta `json:"meta"`
}

func ImportAddRelationRequest

func ImportAddRelationRequest(data []byte) (*SignableRequest, error)

func ImportCreateCardRequest

func ImportCreateCardRequest(data []byte) (*SignableRequest, error)

func ImportDeleteRelationRequest

func ImportDeleteRelationRequest(data []byte) (*SignableRequest, error)

func ImportRevokeCardRequest

func ImportRevokeCardRequest(data []byte) (*SignableRequest, error)

func NewAddRelationRequest

func NewAddRelationRequest(relationCard *Card) (*SignableRequest, error)

func NewCreateCardRequest

func NewCreateCardRequest(identity, identityType string, publicKey virgilcrypto.PublicKey, params CardParams) (*SignableRequest, error)

func NewDeleteRelationRequest

func NewDeleteRelationRequest(relationCardId string) (*SignableRequest, error)

func NewRevokeCardRequest

func NewRevokeCardRequest(id string, revocationReason Enum) (*SignableRequest, error)

func (*SignableRequest) AppendSignature

func (r *SignableRequest) AppendSignature(cardId string, signature []byte)

func (*SignableRequest) Export

func (r *SignableRequest) Export() ([]byte, error)

func (*SignableRequest) MarshalJSON

func (mj *SignableRequest) MarshalJSON() ([]byte, error)

func (*SignableRequest) MarshalJSONBuf

func (mj *SignableRequest) MarshalJSONBuf(buf fflib.EncodingBuffer) error

func (*SignableRequest) UnmarshalJSON

func (uj *SignableRequest) UnmarshalJSON(input []byte) error

func (*SignableRequest) UnmarshalJSONFFLexer

func (uj *SignableRequest) UnmarshalJSONFFLexer(fs *fflib.FFLexer, state fflib.FFParseState) error

type StorageItem

type StorageItem struct {
	Name string
	Data []byte
	Meta map[string]string
}

type ValidateRequest

type ValidateRequest struct {
	Type            string `json:"type"`
	Value           string `json:"value"`
	ValidationToken string `json:"validation_token"`
}

type ValidationInfo

type ValidationInfo struct {
	Token string `json:"token,omitempty"`
}

func (*ValidationInfo) MarshalJSON

func (mj *ValidationInfo) MarshalJSON() ([]byte, error)

func (*ValidationInfo) MarshalJSONBuf

func (mj *ValidationInfo) MarshalJSONBuf(buf fflib.EncodingBuffer) error

func (*ValidationInfo) UnmarshalJSON

func (uj *ValidationInfo) UnmarshalJSON(input []byte) error

func (*ValidationInfo) UnmarshalJSONFFLexer

func (uj *ValidationInfo) UnmarshalJSONFFLexer(fs *fflib.FFLexer, state fflib.FFParseState) error

type ValidationTokenParams

type ValidationTokenParams struct {
	TimeToLive  int `json:"time_to_live"`
	CountToLive int `json:"count_to_live"`
}

type VerifyRequest

type VerifyRequest struct {
	Type        string            `json:"type"`
	Value       string            `json:"value"`
	ExtraFields map[string]string `json:"extra_fields"`
}

type VerifyResponse

type VerifyResponse struct {
	ActionId string `json:"action_id"`
}

type VirgilCardValidator

type VirgilCardValidator struct {
	// contains filtered or unexported fields
}

func NewCardsValidator

func NewCardsValidator() *VirgilCardValidator

NewCardsValidator create a cards validator

func (*VirgilCardValidator) AddDefaultVerifiers

func (v *VirgilCardValidator) AddDefaultVerifiers() error

AddVerifier adds default card service card

func (*VirgilCardValidator) AddVerifier

func (v *VirgilCardValidator) AddVerifier(cardId string, key virgilcrypto.PublicKey)

AddVerifier add new service for validation

func (*VirgilCardValidator) Validate

func (v *VirgilCardValidator) Validate(card *Card) (bool, error)

Validate that all signatures were added

Directories

Path Synopsis
gcm

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL