wwpass-ruby-sdk 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6d53c48089bb729b6f45c2f1f6ad8d11c6239179
-  data.tar.gz: d0a19ed53e5e952d5f9a631c07df71a026321aaf
+  metadata.gz: 04a8dbe5f00fd7df2e918d202a0b1c7fb86d4a7f
+  data.tar.gz: eddbdf94e9b08b5404457f69b603a5eb3f50bef7
 SHA512:
-  metadata.gz: e318c24ac008bcf2ad7a502b3c163b8e76ec0d929271d574153f1c8697e6ac3a66f48d02592d53da58e20ad3f7ad7ff0b26fe78f0524c47d7d3dadb407fa5072
-  data.tar.gz: a592bb4ee2d98fae85a3d1297d4a81453363a9077eb4412ba8e0e4b7395cbc63cdeab083c24699416b912cc26e52e9e494f9db7635c23511dea4e900684638f3
+  metadata.gz: 9f03ae6d3a0b6bea68ee318ffa60c637bb8cb87f8ac04a4bc645596a4bc448bbf556f2a74d698325f19350184ae1bd53afe29cabaac9ca3f809764eec2068546
+  data.tar.gz: 4e916048850176195e37e8e95b4be3b3cf72ccab206a3cb85f715c4d04d83590c93515fe83bbe23aa50c181f3c0c592e793be30158dfb571a1fd4a4f725b425c

data/README.md

@@ -1,8 +1,30 @@
 # WWPass-ruby-sdk
 
-The WWPass connection web application SDK for Ruby allows a service provider to provide authentication using the WWPass system. The WWPass Authentication Service is an alternative to, or replacement for, other authentication methods such as user name/password.
+## OVERVIEW
+### Introduction
+The *WWPass Ruby SDK* allows a service provider to provide authentication using WWPass. WWPass's Authentication Service is an alternative to or replacement for other authentication methods such as username and password.  The Authentication Service works with the WWPass PassKey or WWPass PassKey Lite application on your smart phone.
 
-## Installation
+The **WWPass PassKey** or **WWPass PassKey Lite** is a requirement for user authentication. 
+**PassKey** is a hardware device that enables authentication and access for a given user.  A major component of the WWPass authentication capability is the software that supports the PassKey itself. Without this software, requests to an end user to authenticate their identity will fail since this software is used to directly access information stored on the PassKey and communicate with WWPass. To allow Administrator testing of the authentication infrastructure, this client software and an accompanying PassKey is required. 
+**PassKey Lite** is an application for Android and iOS smartphones and tablets. The application is used to scan QR codes to authenticate into WWPass-enabled sites. Alternatively, when browsing with these mobile devices, you can tap the QR code image to authenticate into the site to access protected information directly on your phone or tablet. 
+For more information about how to obtain a PassKey and register it, please refer to the WWPass web site (<http://www.wwpass.com>)  
+
+### Licensing
+The *WWPass Python SDK* is licensed under the Apache 2.0 license.  This license applies to all source code, code examples and accompanying documentation contained herein.  You can modify and re-distribute the code with the appropriate attribution.  This software is subject to change without notice and should not be construed as a commitment by WWPass.
+
+You may obtain a copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>
+
+Unless required by applicable law or agreed to in writing, the software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+### Customer Assistance
+If you encounter a problem or have a question, you can contact the WWPass Service Desk as follows:
+Phone - 1-888-WWPASS1 (+1-888-997-2771)
+Email - <support@wwpass.com>
+Online - [Support form](https://www.wwpass.com/support/)
+
+
+## Quick Start
+### Installation
 
 Add this line to your application's Gemfile:
 
@@ -18,7 +40,7 @@ Or install it yourself as:
 
     $ gem install wwpass-ruby-sdk
 
-## Usage
+### Usage
 
 WWPass requires access to the certificates that were installed as part of your WWPass installation as described [here](https://developers.wwpass.com/documentation/get-started). We recommend creating a configuration file like `config/wwpass.yml` with contents like
 ```ruby
@@ -38,22 +60,172 @@ production:
 You can then create code (typically in a controller class) that connects to the WWPass Service Provider Front End (spfe) and, for example, fetches a ticket:
 
 ```ruby
-@connection = WWPassConnection.new(WWPASS_CONFIG[:cert_file], WWPASS_CONFIG[:key_file], WWPASS_CONFIG[:cert_ca])
 begin
-  @ticket = @connection.get_ticket(':p')    # Requires access code entry
+  @connection = WWPassRubySDK::WWPassConnection.new(WWPASS_CONFIG[:cert_file], WWPASS_CONFIG[:key_file], WWPASS_CONFIG[:cert_ca])
 rescue WWPassException => e
   # Handle exception
 end
+@ticket = @connection.get_ticket(':p')    # Requires access code entry
 ```
 
 
-## Development
+### Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## Contributing
+### Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/wwpass/wwpass-ruby-sdk.
 
+## Ruby API
+### WWPassConnection Constructor
+#### Signature
+    WWPASSConnection(cert_file, key_file, cafile, timeout, spfe_addr)
+#### Purpose
+*WWPassConnection* is the class for a WWPass SPFE connection, and a new connection is initiated every time a connection request is made.  The WWPass CA certificate is required for validating the SPFE certificate and can be downloaded at <https://developers.wwpass.com/downloads/wwpass.ca>
+#### Parameters
+| Name | Description |
+| --------- | ---------------- | 
+| cert_file | The path to the Service Provider's certificate file. |
+| key_file | The path to the Service Provider's private key file. |
+| cafile |The path to the WWPass Service Provider CA certificate. |
+| timeout | Timeout of requests to SPFE measured in seconds. It is used in all operations. The default is 10 seconds. |
+| spfe_addr | The hostname or base URL of the SPFE. The default name is <https://spfe.wwpass.com>. |
+ 
+### getName
+#### Signature
+    getName()
+#### Purpose
+Gets the service provider name on the certificate which was used initiate this *WWPassConnection* instance.
+
+#### Returns
+The service provider name
+#### Exception (Throw)
+*WWPassException* is thrown if there is an internal formatting error
+
+### getTicket
+#### Signature
+    getTicket(auth_type, ttl)
+#### Purpose
+Gets a newly-issued ticket from SPFE. This ticket is required in all other functions.
+#### Parameters
+| Name | Description |
+| ------- | -------------- |
+| auth_type | Defines which credentials will be asked of the user to authenticate this ticket. The values may be any combination of following letters: ‘p’ — to ask for PassKey and access code; ‘s’ — to generate cryptographically secure random number that would be available both to client and Service Provider; or empty string to ask for PassKey only (default). |
+| ttl |The period in seconds for the ticket to remain valid since issuance. The default is 120 seconds. |
+
+#### Returns
+Ticket string
+
+### getPUID
+#### Signature
+    getPUID(ticket, auth_type)
+#### Purpose
+Gets the id of the user from the Service Provider Front End. This ID is unique for each Service Provider.
+#### Parameters
+| Name | Description |
+| ------- | -------------- |
+| ticket | The authenticated ticket. |
+| auth_type | Defines which credentials will be asked of the user to authenticate this ticket. The values may be any combination of following letters: ‘p’ — to ask for PassKey and access code; ‘s’ — to generate cryptographically secure random number that would be available both to client and Service Provider; or empty string to ask for PassKey only (default). |
+
+#### Returns
+User ID
+
+### putTicket
+#### Signature
+    putTicket(ticket, ttl, auth_type)
+#### Purpose
+Checks the authentication of the ticket and may issue a new ticket from SPFE.  All subsequent operations should use a returned ticket instead of one provided to *putTicket*.
+#### Parameters
+| Name | Description |
+| ------- | -------------- |
+| ticket | The ticket to validate. |
+| ttl | The period in seconds for the ticket to remain valid since issuance. The default is 120 seconds. |
+| auth_type | Defines which credentials will be asked of the user to authenticate this ticket. The values may be any combination of following letters: ‘p’ — to ask for PassKey and access code; ‘s’ — to generate cryptographically secure random number that would be available both to client and Service Provider; or empty string to ask for PassKey only (default). |
+
+#### Returns
+Possibly new ticket
+
+The new ticket should be used in further operations with the SPFE.  
+
+### readData()
+#### Signature
+    readData(ticket, container)
+#### Purpose
+Requests data stored in the user’s data container.
+#### Parameters
+| Name | Description |
+| ------- | -------------- |
+| ticket | The authenticated ticket issued by the SPFE. |
+| container | Arbitrary string (only the first 32 bytes are significant) identifying the user’s data container. |
+
+#### Returns
+Data string
+ 
+### readDataAndLock()
+#### Signature
+    readDataAndLock(ticket, lock_timeout, container)
+#### Purpose
+Requests data stored in the user’s data container and tries to atomically lock an associated lock.
+#### Parameters
+| Name | Description |
+| ------- | -------------- |
+| ticket | The authenticated ticket issued by the SPFE. |
+| lock_timeout | The period in seconds for the data container to remain protected from the new data being accessed. |
+| container | Arbitrary string (only the first 32 bytes are significant) identifying the user’s data container. |
+
+#### Returns
+Data string
+
+### writeData()
+#### Signature
+    writeData(ticket, data, container)
+#### Purpose
+Write data into the user’s data container.
+#### Parameters
+| Name | Description |
+| ------- | -------------- |
+| ticket | The authenticated ticket issued by the SPFE. |
+| data | The string to write into the container. |
+| container | Arbitrary string (only the first 32 bytes are significant) identifying the user’s data container. |
+
+#### Returns
+`(True, None)` or
+`(False, <error message>)` 
+
+### writeDataAndUnlock
+#### Signature
+    writeDataAndUnlock(ticket, data, container)
+#### Purpose
+Writes data into the user's data container and unlocks an associated lock. If the lock is already unlocked, the write will succeed, but the function will return an appropriate error.
+#### Parameters
+| Name | Description |
+| ------- | -------------- |
+| ticket | The authenticated ticket issued by the SPFE. |
+| data | The string to write into the container. |
+| container | Arbitrary string (only the first 32 bytes are significant) identifying the user’s data container. |
+
+### lock
+#### Signature
+    lock(ticket, lockTimeout, lockid)
+#### Purpose
+Tries to lock a lock identified by the user (by authenticated ticket) and lock ID.
+#### Parameters
+| Name | Description |
+| ------- | -------------- |
+| ticket | The authenticated ticket issued by the SPFE. |
+| lockTimeout | The period in seconds for the data container to remain protected from the new data being accessed. |
+| lockid | The arbitrary string (only the first 32 bytes are significant) identifying the lock. |
+ 
+### unlock
+#### Signature
+    unlock(ticket, lockid)
+#### Purpose
+Tries to unlock a lock identified by the user (by authenticated ticket) and lock ID.
+##### Parameters
+| Name | Description |
+| ------- | -------------- |
+| ticket | The authenticated ticket issued by the SPFE. |
+| lockid | The arbitrary string (only the first 32 bytes are significant) identifying the lock. |

data/lib/wwpass-ruby-sdk.rb

@@ -1 +1,2 @@
 require 'wwpass-ruby-sdk/wwpass_connection'
+require 'wwpass-ruby-sdk/wwpass_exception'

data/lib/wwpass-ruby-sdk/wwpass_connection.rb

@@ -2,7 +2,6 @@ require 'restclient'
 require 'openssl'
 require 'json'
 require 'base64'
-require 'wwpass_exception'
 
 class WWPassConnection
   def initialize(cert_file, key_file, cafile, timeout = 10, spfe_addr = 'https://spfe.wwpass.com')

data/wwpass-ruby-sdk.gemspec

@@ -5,7 +5,7 @@ require 'wwpass-ruby-sdk/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'wwpass-ruby-sdk'
-  spec.version       = '0.1.0'
+  spec.version       = '0.1.1'
   spec.authors       = ['Stanislav Panyushkin']
   spec.email         = ['opensource@wwpass.com']
   spec.license       = 'Apache-2.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wwpass-ruby-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Stanislav Panyushkin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-04-11 00:00:00.000000000 Z
+date: 2016-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler