Commits

Toby Inkster committed a3966dc Draft

much documentation

  • Participants
  • Parent commits d2a87f7

Comments (0)

Files changed (15)

 * Need to look at manifest verification.
-* Documentation desparately needs improvement.
 * Better Web::ID and RDF::ACL integration.
 package RDF::Crypt;
 
-use 5.008;
+use 5.010;
 
 use RDF::Crypt::Verifier;
 use RDF::Crypt::Signer;
 
 =head1 DESCRIPTION
 
-This module provides a variety of objects and methods for cryptographically
+RDF-Crypt provides a variety of objects and methods for cryptographically
 manipulating (encrypting, decrypting, signing and verifying) RDF graphs using
 RSA and WebID.
 
+RDF-Crypt uses a role-based architecture. Classes like RDF::Crypt::Encrypter
+are in fact very slim wrappers around collections of roles. Most of the
+interesting behaviour is documented in the role modules.
+
 =head1 SEE ALSO
 
 L<RDF::Crypt::Encrypter>,
 L<RDF::Crypt::Signer>,
 L<RDF::Crypt::Verifier>.
 
+L<Web::ID>, L<RDF::ACL>.
+
+L<http://www.perlrdf.org/>.
+
 =head1 BUGS
 
 Please report any bugs to L<http://rt.cpan.org/>.
 
 =head1 COPYRIGHT
 
-Copyright 2010 Toby Inkster
+Copyright 2010, 2012 Toby Inkster
 
 This library is free software; you can redistribute it and/or modify it
 under the same terms as Perl itself.
 
-=cut
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Decrypter.pm

 
 1;
 
+__END__
+
 =head1 NAME
 
-RDF::Crypt::Decrypter - decryptes encrypted RDF graphs
+RDF::Crypt::Decrypter - decrypts encrypted RDF graphs
 
 =head1 DESCRIPTION
 
 A Decrypter object is created using an RSA private key.
 
-RDF::Crypt::Decrypter is a subclass of RDF::Crypt::Encrypter, and can thus
-also be used to encrypt graphs for yourself, using just your private key. See
-L<RDF::Crypt::Encrypter> for details of the encryption methods.
+RDF::Crypt::Decrypter can also also be used to encrypt graphs for yourself,
+using just your private key. See L<RDF::Crypt::Role::DoesEncrypt> for
+details of the encryption methods.
 
-=head2 Constructors
+=head2 Roles
 
 =over
 
-=item C<< new_from_file($file) >>
+=item * L<RDF::Crypt::Role::WithPublicKeys>
 
-Given a filename containing a DER or PEM encoded RSA private key, constructs
-a Decrypter object.
+=item * L<RDF::Crypt::Role::DoesDecrypt>
 
-=item C<< new_from_string($str) >>
+=item * L<RDF::Crypt::Role::DoesEncrypt>
 
-Given a string containing a DER or PEM encoded RSA private key, constructs
-a Decrypter object.
-
-=item C<< new_from_privkey($key) >>
-
-Given a L<Crypt::OpenSSL::RSA> private key object, constructs a Decrypter object.
+=item * L<RDF::Crypt::Role::ToString>
 
 =back
 
-=head2 Object Methods
+=begin trustme
 
-=over
+=item * encrypt_bytes
 
-=item C<< decrypt_model($text, %opts) >>
+=item * decrypt_bytes
 
-Given a string that represents an encrypted RDF graph, decrypts and
-parses it. Any options are passed along to L<RDF::TrineShortcuts>'
-C<rdf_parse> function.
-
-Returns an L<RDF::Trine::Model>.
-
-=item C<< decrypt_text($str) >>
-
-Bonus method - decrypts a literal string which may or may not have anything
-to do with RDF.
-
-=back
+=end trustme
 
 =head1 SEE ALSO
 
+L<RDF::Crypt>,
 L<RDF::Crypt::Encrypter>.
 
 =head1 BUGS
 
 =head1 COPYRIGHT
 
-Copyright 2010 Toby Inkster
+Copyright 2010, 2012 Toby Inkster
 
 This library is free software; you can redistribute it and/or modify it
 under the same terms as Perl itself.
 
-=cut
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Encrypter.pm

 use MIME::Base64 qw[decode_base64 encode_base64];
 use RDF::TrineX::Functions -shortcuts;
 use MIME::Base64 qw[];
-use RDF::TrineX::Functions -shortcuts;
 use Sys::Hostname qw[];
 
 use namespace::clean;
 
 1;
 
+__END__
+
 =head1 NAME
 
 RDF::Crypt::Encrypter - encrypts RDF graphs
 An Encrypter object is created using an RSA public key. The object can be used
 to encrypt an RDF graph for a recipient.
 
-=head2 Constructors
+=head2 Roles
 
 =over
 
-=item C<< new_from_file($file) >>
+=item * L<RDF::Crypt::Role::WithPublicKeys>
 
-Given a filename containing a DER or PEM encoded RSA public key, constructs
-an Encrypter object.
+=item * L<RDF::Crypt::Role::DoesEncrypt>
 
-=item C<< new_from_string($str) >>
-
-Given a string containing a DER or PEM encoded RSA public key, constructs
-an Encrypter object.
-
-=item C<< new_from_pubkey($key) >>
-
-Given a L<Crypt::OpenSSL::RSA> public key object, constructs an Encrypter object.
-
-=item C<< new_from_webid($uri) >>
-
-Given a WebID with one of more FOAF+SSL public keys, constructs an Encrypter
-object. If multiple public keys are associated with the same WebID, then the one
-with the largest key size (most secure) is used.
+=item * L<RDF::Crypt::Role::ToString>
 
 =back
 
-=head2 Object Methods
+=begin trustme
 
-=over
+=item * encrypt_bytes
 
-=item C<< encrypt_model($model) >>
-
-Returns an encrypted serialisation of the data.
-
-The encryption works by serialising the data as RDF/XML, then
-encrypting it with C<encrypt_text>.
-
-=item C<< send_model_by_email($model, \%opts) >>
-
-This method only works on objects that were constructed using C<new_from_webid>.
-Encrypts the model for the holder of the WebID, and sends it to an address
-specified in the WebID profile using foaf:mbox.
-
-Options:
-
-=over
-
-=item * B<sendmail> - hashref of options for L<Mail::Transport::Sendmail>. The
-mere presence of this hashref will trigger L<Mail::Transport::Sendmail> to
-be used as the delivery method.
-
-=item * B<smtp> - hashref of options for L<Mail::Transport::SMTP>. The
-mere presence of this hashref will trigger L<Mail::Transport::SMTP> to
-be used as the delivery method.
-
-=item * B<from> - email address for the message to come from.
-
-=item * B<subject> - message subject.
-
-=item * B<filename> - filename for encrypted attachment.
-
-=item * B<headers> - hashref of additional mail headers.
-
-=back
-
-Returns a the message's Message-ID, or undef if unsuccessful.
-
-=item C<< encrypt_text($str) >>
-
-Bonus method - encrypts a literal string which may or may not have anything
-to do with RDF.
-
-The return value is a base64-encoded string. The base64-decoded value consists
-of: (1) an initialisation vector, sixteen bytes shorter than the size of the
-key; (2) a 16-bit big-endian signed integer indicating the length of padding
-which was added to the payload of the message during encryption; (3) the payload,
-encrypted using cipher-block chaining with OAEP, with block length sixteen bytes
-shorter than the key size. These three parts are concatenated together in that
-order.
-
-=back
+=end trustme
 
 =head1 SEE ALSO
 
+L<RDF::Crypt>,
 L<RDF::Crypt::Decrypter>.
 
 =head1 BUGS
 
 =head1 COPYRIGHT
 
-Copyright 2010 Toby Inkster
+Copyright 2010, 2012 Toby Inkster
 
 This library is free software; you can redistribute it and/or modify it
 under the same terms as Perl itself.
 
-=cut
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Role/DoesDecrypt.pm

 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+RDF::Crypt::Role::DoesDecrypt - unscrambling methods
+
+=head1 DESCRIPTION
+
+=head2 Object Methods
+
+=over
+
+=item C<< decrypt_model($text, %opts) >>
+
+Given a string that represents an encrypted RDF graph, decrypts and
+parses it. Any options are passed along to L<RDF::TrineX::Functions>
+C<parse> function.
+
+Returns an L<RDF::Trine::Model>.
+
+=item C<< decrypt_text($str) >>
+
+Decrypts a literal string which may or may not have anything
+to do with RDF.
+
+=back
+
+=head2 Required Methods
+
+This role does not implement these methods, but requires classes to
+implement them instead:
+
+=over
+
+=item C<< decrypt_bytes($str) >>
+
+Unscrambles an octet string.
+
+=back
+
+=head1 SEE ALSO
+
+L<RDF::Crypt>,
+L<RDF::Crypt::Decrypter>.
+
+=head1 BUGS
+
+Please report any bugs to L<http://rt.cpan.org/>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT
+
+Copyright 2010, 2012 Toby Inkster
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Role/DoesEncrypt.pm

 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+RDF::Crypt::Role::DoesEncrypt - scrambling methods
+
+=head1 DESCRIPTION
+
+=head2 Object Methods
+
+=over
+
+=item C<< encrypt_model($model) >>
+
+Returns an encrypted serialisation of the data.
+
+The encryption works by serialising the data as RDF/XML, then
+encrypting it with C<encrypt_text>.
+
+=item C<< send_model_by_email($model, \%opts) >>
+
+This method only works on objects that were constructed using C<new_from_webid>.
+Encrypts the model for the holder of the WebID, and sends it to an address
+specified in the WebID profile using foaf:mbox.
+
+Options:
+
+=over
+
+=item * B<sendmail> - hashref of options for L<Mail::Transport::Sendmail>. The
+mere presence of this hashref will trigger L<Mail::Transport::Sendmail> to
+be used as the delivery method.
+
+=item * B<smtp> - hashref of options for L<Mail::Transport::SMTP>. The
+mere presence of this hashref will trigger L<Mail::Transport::SMTP> to
+be used as the delivery method.
+
+=item * B<from> - email address for the message to come from.
+
+=item * B<subject> - message subject.
+
+=item * B<filename> - filename for encrypted attachment.
+
+=item * B<headers> - hashref of additional mail headers.
+
+=back
+
+Returns a the message's Message-ID, or undef if unsuccessful.
+
+=item C<< encrypt_text($str) >>
+
+Encrypts a literal string which may or may not have anything
+to do with RDF.
+
+The return value is a base64-encoded string. The base64-decoded value consists
+of: (1) an initialisation vector, sixteen bytes shorter than the size of the
+key; (2) a 16-bit big-endian signed integer indicating the length of padding
+which was added to the payload of the message during encryption; (3) the payload,
+encrypted using cipher-block chaining with OAEP, with block length sixteen bytes
+shorter than the key size. These three parts are concatenated together in that
+order.
+
+=back
+
+=head2 Required Methods
+
+This role does not implement these methods, but requires classes to
+implement them instead:
+
+=over
+
+=item C<< encrypt_bytes($str) >>
+
+Scrambles an octet string.
+
+=back
+
+=head1 SEE ALSO
+
+L<RDF::Crypt>,
+L<RDF::Crypt::Encrypter>,
+L<RDF::Crypt::Decrypter>.
+
+=head1 BUGS
+
+Please report any bugs to L<http://rt.cpan.org/>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT
+
+Copyright 2010, 2012 Toby Inkster
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Role/DoesSign.pm

 }
 
 1;
+
+
+__END__
+
+=head1 NAME
+
+RDF::Crypt::Role::DoesSign - signing methods
+
+=head1 DESCRIPTION
+
+=head2 Object Methods
+
+=over
+
+=item C<< sign_model($model) >>
+
+Given an L<RDF::Trine::Model>, returns a signature as a string.
+
+The model is converted to a canonicalised N-Triples representation (see
+L<RDF::Trine::Serializer::NTriples::Canonical>) with any triples that
+cannot be canonicalised being truncated. This representation is then
+signed using an MD5 digest, and the resulting binary signature encoded
+using base64.
+
+=item C<< generate_manifest($webid, \@urls) >>
+
+Given a WebID that people can use to recover your public key, and a
+list of URLs that need signing, signs each and returns an
+L<RDF::Trine::Model> containing the results of processing. This
+can be serialised as, say, Turtle to act as an endorsement for
+a bunch of RDF graphs.
+
+=item C<< sign_embed_turtle($turtle, $baseuri) >>
+
+Parses the given Turtle into a model, generates a signature for that
+and then returns the original Turtle with the signature embedded as
+a comment. This allows the signature to sit in the same file as the
+data itself.
+
+The base URI is used to resolve any relative URI references. Note that
+if a different base URI is provided when verifying the signature, this
+may cause verification to fail. The base URI is optional.
+
+=item C<< sign_embed_rdfxml($xml, $baseuri) >>
+
+As per C<sign_embed_turtle>, but RDF/XML.
+
+=item C<< sign_embed_rdfa($html, $baseuri, \%config) >>
+
+Similar to C<sign_embed_turtle> and C<sign_embed_rdfxml>. The base
+URI is required. A set of configuration options may be provided,
+which will be passed along to L<RDF::RDFa::Parser>'s constructor.
+
+Rather than storing the signature as an XML/HTML comment, the
+signature is stored on the root element as an attribute.
+
+=item C<< sign_text($str) >>
+
+Signs a literal string which may or may not have anything to do with RDF.
+
+=back
+
+=head2 Required Methods
+
+This role does not implement these methods, but requires classes to
+implement them instead:
+
+=over
+
+=item C<< sign_bytes($str) >>
+
+Generates a signature for an octet string.
+
+=item C<< SIG_MARK >>
+
+Returns a string used as a marker for signatures within serialised RDF.
+
+=back
+
+=head1 SEE ALSO
+
+L<RDF::Crypt>,
+L<RDF::Crypt::Signer>.
+
+=head1 BUGS
+
+Please report any bugs to L<http://rt.cpan.org/>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT
+
+Copyright 2010, 2012 Toby Inkster
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Role/DoesVerify.pm

 {
 	my ($class, $data, %opts) = @_;
 	
+	confess "$class cannot new_from_webid"
+		unless $class->can('new_from_webid');
+	
 	$data = rdf_parse($data, %opts);
 	
 	my $query_string = <<'QUERY';
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+RDF::Crypt::Role::DoesVerify - verification methods
+
+=head1 DESCRIPTION
+
+=head2 Class Methods
+
+=over
+
+=item C<< verify_manifest($manifest) >>
+
+Given a manifest created by the Signer, attempts to verify each signature
+in it. Returns a list of hashrefs such that each hashref has the following
+keys:
+
+=over
+
+=item * B<document> - the URI of the thing that was signed
+
+=item * B<signer> - the WebID of the agent that signed it
+
+=item * B<signedAt> - signature datetime
+
+=item * B<signature> - base64 RSA signature
+
+=item * B<verification> - true/false/undef (see C<verify_model>)
+
+=back
+
+=back
+
+=head2 Object Methods
+
+=over
+
+=item C<< verify_model($model, $signature) >>
+
+Returns true if verification was successful; false but defined if
+verification failed; undefined if verification was not attempted
+for some reason.
+
+=item C<< verify_embedded_turtle($turtle, $baseuri) >>
+
+Counterpart to C<sign_embed_turtle> from L<RDF::Crypt::Role::DoesSign>.
+
+=item C<< verify_embedded_rdfxml($xml, $baseuri) >>
+
+Counterpart to C<sign_embed_rdfxml> from L<RDF::Crypt::Role::DoesSign>.
+
+=item C<< verify_embedded_rdfa($html, $baseuri, \%config) >>
+
+Counterpart to C<sign_embed_rdfa> from L<RDF::Crypt::Role::DoesSign>.
+
+=item C<< verify_text($str, $signature) >>
+
+Verifies a character string which may or may not have anything to do with RDF.
+
+=back
+
+=head2 Required Methods
+
+This role does not implement these methods, but requires classes to
+implement them instead:
+
+=over
+
+=item C<< verify_bytes($str, $signature) >>
+
+Verifies that an octet string satisfies the signature.
+
+=item C<< SIG_MARK >>
+
+Returns a string used as a marker for signatures within serialised RDF.
+
+=back
+
+=head1 SEE ALSO
+
+L<RDF::Crypt>,
+L<RDF::Crypt::Verifier>,
+L<RDF::Crypt::Signer>.
+
+=head1 BUGS
+
+Please report any bugs to L<http://rt.cpan.org/>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT
+
+Copyright 2010, 2012 Toby Inkster
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Role/StandardSignatureMarkers.pm

 
 use constant SIG_MARK => 'CANONICAL_SIGNATURE';
 
-1;
+1;
+
+__END__
+
+=head1 NAME
+
+RDF::Crypt::Role::StandardSignatureMarkers - provides SIG_MARK method
+
+=head1 DESCRIPTION
+
+This method is needed by L<RDF::Crypt::Signer> and L<RDF::Crypt::Verifier>
+so that the verifier can find the signatures generated by the signer.
+
+=head2 Constant
+
+=over
+
+=item C<< SIG_MARK >>
+
+String marker for the signature.
+
+=back
+
+=head1 SEE ALSO
+
+L<RDF::Crypt>,
+L<RDF::Crypt::Role::DoesSign>,
+L<RDF::Crypt::Role::DoesVerify>,
+L<RDF::Crypt::Signer>,
+L<RDF::Crypt::Verifier>.
+
+=head1 BUGS
+
+Please report any bugs to L<http://rt.cpan.org/>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT
+
+Copyright 2010, 2012 Toby Inkster
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Role/ToString.pm

 #	q[""]    => 'to_string',
 #	q[bool]  => sub { 1 },
 #	fallback => 1;
-use constant LENGTH => 72;
+use constant _LENGTH => 72;
 
 BEGIN {
 	$RDF::Crypt::Role::ToString::AUTHORITY = 'cpan:TOBYINK';
 	$title //= ref $self;
 	
 	my $str;
-	$str .= ('=' x LENGTH) . "\n";
+	$str .= ('=' x $self->_LENGTH) . "\n";
 	$str .= $title . "\n";
 	if ($self->can('private_key'))
 	{
 		my @keys = @{ $self->public_keys || [] };
 		$str .= $self->_key_to_string($keys[$_], "Public Key $_") for 0 .. $#keys;
 	}
-	$str .= ('=' x LENGTH) . "\n";
+	$str .= ('=' x $self->_LENGTH) . "\n";
 	return $str;
 }
 
 {
 	my ($self, $key, $title) = @_;
 	my $str;
-	$str .= ('-' x LENGTH) . "\n";
+	$str .= ('-' x $self->_LENGTH) . "\n";
 	$str .= $title . "\n";
 	$str .= $key->get_public_key_string;
 	return $str;
 
 1;
 
+__END__
+
+=head1 NAME
+
+RDF::Crypt::Role::ToString - provides a data dump
+
+=head1 DESCRIPTION
+
+This is fairly handy as Data::Dumper doesn't peek inside Crypt::OpenSSL::RSA
+keys.
+
+=head2 Object Method
+
+=over
+
+=item C<< to_string($title) >>
+
+Returns a string representing the object, with an optional title.
+
+=back
+
+Ultimately this will probably use L<overload>, but it doesn't right now.
+
+=head1 SEE ALSO
+
+L<RDF::Crypt>,
+L<RDF::Crypt::Encrypter>,
+L<RDF::Crypt::Decrypter>,
+L<RDF::Crypt::Signer>,
+L<RDF::Crypt::Verifier>.
+
+=head1 BUGS
+
+Please report any bugs to L<http://rt.cpan.org/>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT
+
+Copyright 2010, 2012 Toby Inkster
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Role/WithPrivateKey.pm

 
 1;
 
+__END__
+
+=head1 NAME
+
+RDF::Crypt::Role::WithPublicKeys - role for objects that have public keys
+
+=head1 DESCRIPTION
+
+=head2 Attribute
+
+=over
+
+=item C<< private_key >>
+
+Read only; Crypt::OpenSSL::RSA; required.
+
+=back
+
+=head2 Additional Constructor Methods
+
+=over
+
+=item C<< new_from_file($file) >>
+
+Given a filename containing a DER or PEM encoded RSA private key, constructs
+an object.
+
+=item C<< new_from_string($str) >>
+
+Given a string containing a DER or PEM encoded RSA private key, constructs
+an object.
+
+=item C<< new_from_privkey($key) >>
+
+Given a L<Crypt::OpenSSL::RSA> private key object, constructs an object.
+
+=back
+
+=head1 SEE ALSO
+
+L<RDF::Crypt>,
+L<RDF::Crypt::Decrypter>,
+L<RDF::Crypt::Signer>.
+
+=head1 BUGS
+
+Please report any bugs to L<http://rt.cpan.org/>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT
+
+Copyright 2010, 2012 Toby Inkster
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Role/WithPublicKeys.pm

 
 1;
 
+__END__
+
+=head1 NAME
+
+RDF::Crypt::Role::WithPublicKeys - role for objects that have public keys
+
+=head1 DESCRIPTION
+
+=head2 Attributes
+
+=over
+
+=item C<< public_keys >>
+
+Read only; ArrayRef[Crypt::OpenSSL::RSA]; lazy build.
+
+=item C<< webid >>
+
+Read only; Str.
+
+=item C<< webid_san >>
+
+Read only; Web::ID::SAN::URI|Undef; lazy build.
+
+=back
+
+=head2 Additional Constructor Methods
+
+=over
+
+=item C<< new_from_file($file) >>
+
+Given a filename containing a DER or PEM encoded RSA public key, constructs
+an object.
+
+=item C<< new_from_string($str) >>
+
+Given a string containing a DER or PEM encoded RSA public key, constructs
+an object.
+
+=item C<< new_from_pubkey($key) >>
+
+Given a L<Crypt::OpenSSL::RSA> public key object, constructs an object.
+
+=item C<< new_from_webid($uri) >>
+
+Given a WebID URI with one of more FOAF+SSL public keys, constructs an 
+object. If multiple public keys are associated with the same WebID, then
+the one with the largest key size (most secure) is typically used.
+
+=back
+
+=head2 Object Method
+
+=over
+
+=item C<< webid_model >>
+
+Calls C<model> on C<webid_san>.
+
+=back
+
+=head1 SEE ALSO
+
+L<RDF::Crypt>,
+L<RDF::Crypt::Encrypter>,
+L<RDF::Crypt::Verifier>.
+
+=head1 BUGS
+
+Please report any bugs to L<http://rt.cpan.org/>.
+
+=head1 AUTHOR
+
+Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
+
+=head1 COPYRIGHT
+
+Copyright 2010, 2012 Toby Inkster
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Signer.pm

 );
 
 use namespace::clean;
-use constant SIG_MARK => 'CANONICAL_SIGNATURE';  # DRY violation!
 
 BEGIN {
 	$RDF::Crypt::Signer::AUTHORITY = 'cpan:TOBYINK';
 
 1;
 
+__END__
+
 =head1 NAME
 
 RDF::Crypt::Signer - signs RDF graphs with RSA
 serialisation used, so that Turtle and RDF/XML files containing equivalent
 triples should generate the same signature.
 
-RDF::Crypt::Signer is a subclass of RDF::Crypt::Verifier, and can thus
-also be used to verify signatures using the private key of the signer. See
-L<RDF::Crypt::Verifier> for details of the verification methods.
+RDF::Crypt::Signer can also be used to verify signatures using the private
+key of the signer.
 
-=head2 Constructors
+=head2 Roles
 
 =over
 
-=item C<< new_from_file($file) >>
+=item * L<RDF::Crypt::Role::WithPrivateKey>
 
-Given a filename containing a DER or PEM encoded RSA private key, constructs
-a Signer object.
+=item * L<RDF::Crypt::Role::DoesSign>
 
-=item C<< new_from_string($str) >>
+=item * L<RDF::Crypt::Role::DoesVerify>
 
-Given a string containing a DER or PEM encoded RSA private key, constructs
-a Signer object.
+=item * L<RDF::Crypt::Role::StandardSignatureMarkers>
 
-=item C<< new_from_privkey($key) >>
-
-Given a L<Crypt::OpenSSL::RSA> private key object, constructs a Signer object.
+=item * L<RDF::Crypt::Role::ToString>
 
 =back
 
-=head2 Object Methods
+=begin trustme
 
-=over
+=item * sign_bytes
 
-=item C<< sign_model($model) >>
+=item * verify_bytes
 
-Given an L<RDF::Trine::Model>, returns a signature as a string.
+=item * SIG_MARK
 
-The model is converted to a canonicalised N-Triples representation (see
-L<RDF::Trine::Serializer::NTriples::Canonical>) with any triples that
-cannot be canonicalised being truncated. This representation is then
-signed using an MD5 digest, and the resulting binary signature encoded
-using base64.
-
-=item C<< generate_manifest($webid, \@urls) >>
-
-Given a WebID that people can use to recover your public key, and a
-list of URLs that need signing, signs each and returns an
-L<RDF::Trine::Model> containing the results of processing. This
-can be serialised as, say, Turtle to act as an endorsement for
-a bunch of RDF graphs.
-
-=item C<< sign_embed_turtle($turtle, $baseuri) >>
-
-Parses the given Turtle into a model, generates a signature for that
-and then returns the original Turtle with the signature embedded as
-a comment. This allows the signature to sit in the same file as the
-data itself.
-
-The base URI is used to resolve any relative URI references. Note that
-if a different base URI is provided when verifying the signature, this
-may cause verification to fail. The base URI is optional.
-
-=item C<< sign_embed_rdfxml($xml, $baseuri) >>
-
-As per C<sign_embed_turtle>, but RDF/XML.
-
-=item C<< sign_embed_rdfa($html, $baseuri, \%config) >>
-
-Similar to C<sign_embed_turtle> and C<sign_embed_rdfxml>. The base
-URI is required. A set of configuration options may be provided,
-which will be passed along to L<RDF::RDFa::Parser>'s constructor.
-
-Rather than storing the signature as an XML/HTML comment, the
-signature is stored on the root element as an attribute.
-
-=item C<< sign_text($str) >>
-
-Bonus method - signs a literal string which may or may not have anything
-to do with RDF.
-
-=back
+=end trustme
 
 =head1 SEE ALSO
 
+L<RDF::Crypt>,
 L<RDF::Crypt::Verifier>.
 
 =head1 BUGS
 
 =head1 COPYRIGHT
 
-Copyright 2010 Toby Inkster
+Copyright 2010, 2012 Toby Inkster
 
 This library is free software; you can redistribute it and/or modify it
 under the same terms as Perl itself.
 
-=cut
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

lib/RDF/Crypt/Verifier.pm

 }
 
 1;
+__END__
 
 =head1 NAME
 
 A Verifier object is created using an RSA public key. The object can be used
 to verify signatures for multiple RDF graphs.
 
-=head2 Constructors
+=head2 Roles
 
 =over
 
-=item C<< new_from_file($file) >>
+=item * L<RDF::Crypt::Role::WithPublicKeys>
 
-Given a filename containing a DER or PEM encoded RSA public key, constructs
-a Verifier object.
+=item * L<RDF::Crypt::Role::DoesVerify>
 
-=item C<< new_from_string($str) >>
+=item * L<RDF::Crypt::Role::StandardSignatureMarkers>
 
-Given a string containing a DER or PEM encoded RSA public key, constructs
-a Verifier object.
-
-=item C<< new_from_pubkey($key) >>
-
-Given a L<Crypt::OpenSSL::RSA> public key object, constructs a Verifier object.
-
-=item C<< new_from_webid($uri) >>
-
-Given a WebID with one of more FOAF+SSL public keys, constructs a Verifier
-object.
+=item * L<RDF::Crypt::Role::ToString>
 
 =back
 
-=head2 Class Methods
+=begin trustme
 
-=over
+=item * verify_bytes
 
-=item C<< verify_manifest($manifest) >>
-
-Given a manifest created by the Signer, attempts to verify each signature
-in it. Returns a list of hashrefs such that each hashref has the following
-keys:
-
-=over
-
-=item * B<document> - the URI of the thing that was signed
-
-=item * B<signer> - the WebID of the agent that signed it
-
-=item * B<signedAt> - signature datetime
-
-=item * B<signature> - base64 RSA signature
-
-=item * B<verification> - true/false/undef (see C<verify_model>)
-
-=back
-
-=back
-
-=head2 Object Methods
-
-=over
-
-=item C<< verify_model($model, $signature) >>
-
-Returns true if verification was successful; false but defined if
-verification failed; undefined if verification was not attempted
-for some reason.
-
-=item C<< verify_embedded_turtle($turtle, $baseuri) >>
-
-Counterpart to Signer's C<sign_embed_turtle>.
-
-=item C<< verify_embedded_rdfxml($xml, $baseuri) >>
-
-Counterpart to Signer's C<sign_embed_rdfxml>.
-
-=item C<< verify_embedded_rdfa($html, $baseuri, \%config) >>
-
-Counterpart to Signer's C<sign_embed_rdfa>.
-
-=item C<< verify_text($str, $signature) >>
-
-Bonus method - verifies a literal string which may or may not have anything
-to do with RDF.
-
-=back
+=end trustme
 
 =head1 SEE ALSO
 
+L<RDF::Crypt>,
 L<RDF::Crypt::Signer>.
 
 =head1 BUGS
 
 =head1 COPYRIGHT
 
-Copyright 2010 Toby Inkster
+Copyright 2010, 2012 Toby Inkster
 
 This library is free software; you can redistribute it and/or modify it
 under the same terms as Perl itself.
 
-=cut
+=head1 DISCLAIMER OF WARRANTIES
+
+THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+

xt/02pod_coverage.t

-use Test::More skip_all => 'needs work';
+use Test::More;
 use Test::Pod::Coverage;
 
 my @modules =
 		lib/RDF/Crypt/Role/WithPrivateKey.pm
 		lib/RDF/Crypt/Role/WithPublicKeys.pm
 	);
-pod_coverage_ok($_, "$_ is covered")
-	foreach @modules;
+
+pod_coverage_ok(
+	$_,
+	"$_ is covered",
+) foreach @modules;
+
 done_testing(scalar @modules);