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.

cpanm Net::OneTimeSecret

perl -MCPAN -e shell
install Net::OneTimeSecret