/ 
Net-OneTimeSecret-0.04
River stage zero No dependents
/ Net::OneTimeSecret

NAME

Net::OneTimeSecret - Perl interface to OneTimeSecret.com API

SYNOPSIS

use Net::OneTimeSecret;

$api = Net::OneTimeSecret->new( <your customer id>, <your API key> );

$response = $api->shareSecret( "Attack at dawn" );
$secretKey = $response->{secret_key};

$retrievedMessage = $api->retrieveSecret( $secretKey );
print $retrievedMessage->{value};
Attack at dawn

$retrieveAgain = $api->retrieveSecret( $secretKey );
print $retrieveAgain->{value}; # value is empty

VERSION

0.03

FEATURES

  • Very thin wrapper

    You have full access to arguments and returned values for all the REST API calls.

  • Transparent

    You call it with Perl data, and get back Perl data. No messing with encoding or decoding of JSON.

  • Unicode

    Unicode, errrm, seems to work OK.

DESCRIPTION

See https://onetimesecret.com if you don't know how it works or what it's for.

To use, you create an api object by instantiating a Net::OneTimeSecret using your customer id (which is the email address with which you signed up for your API account) and your api key (which you need to generate at https://onetimesecret.com).

METHODS

status

my $response = $api->status();

If $response->{status} is equal to "nominal" then the system is up.

shareSecret

my $response = $api->shareSecret( <secret>, [options] );

where options can be

recipient => <email address>

This will send recipient an email notifying them that there is a secret for them to collect

passphrase => <passphrase>

A passphrase that the recipient will need to know in order to retrieve the secret

ttl => <seconds>

How long the secret will last

It will return a hash like this:

{
  "custid": <this is you>,
  "value": <secret>,
  "metadata_key": <metadata key>,
  "secret_key": <secret key>,
  "ttl": <seconds>,
  "updated": <utc>,
  "created": <utc>
}

retrieveSecret

my $response = $api->retrieveSecret( <secret>, [ passphrase => <passphrase> ] );

There is only one possible option:

passphrase => <passphrase>

A passphrase that the recipient will need to know in order to retrieve the secret

It will return a hash like this:

{
  "custid": <this is you>,
  "value": <secret>,
  "metadata_key": <metadata key>,
  "secret_key": <secret key>,
  "ttl": <seconds>,
  "updated": <utc>,
  "created": <utc>
}

generateSecret

This generates a secret (useful for creating passwords, ids, etc) that can be viewed only once.

my $response = $api->generateSecret( [options] );

where options can be

recipient => <email address>

This will send recipient an email notifying them that there is a secret for them to collect

passphrase => <passphrase>

A passphrase that the recipient will need to know in order to retrieve the secret

ttl => <seconds>

How long the secret will last

It will return a hash like this:

{
  "custid": <this is you>,
  "value": <secret>,
  "metadata_key": <metadata key>,
  "secret_key": <secret key>,
  "ttl": <seconds>,
  "updated": <utc>,
  "created": <utc>
}

retrieveMetadata

my $response = $api->retrieveMetadata( <metadata_key> );

It will return a hash like this:

{
  "custid": <this is you>,
  "metadata_key": <metadata key>,
  "secret_key": <secret key>,
  "ttl": <seconds>,
  "updated": <utc>,
  "created": <utc>
}

TODO

  • Error handling

    Right now you're on your own to test for errors and trap explosions.

  • Bulletproofing

    There are lots of cases that could have slipped through the cracks, so it will need some cleaning up and bulletproofing to harden it a bit.

BUGS

Please report bugs relevant to OneTimeSecret to <info[at]kyledawkins.com>.

CONTRIBUTING

The github repository is at https://quile@github.com/quile/onetime-perl.git

SEE ALSO

Some other stuff.

AUTHOR

Kyle Dawkins, <info[at]kyledawkins.com>

COPYRIGHT AND LICENSE

Copyright 2011 by Kyle Dawkins

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.