Mojo/SAML/Entity.pm untested

filter: Statementstmt 0.0% 0 / 114 Branchbran 0.0% 0 / 32 Conditioncond 0.0% 0 / 8 MC/DCmcdc 0.0% 0 / 5 Subroutinesub 0.0% 0 / 26 Podpod 0.0% 0 / 14 totaltotal 0.0% 0 / 199 CC 15 SCAR 21.5
CC
15
Cov
0%
certificate_for
30.0
from
12.0
name_id_format
12.0
CRAP 8.6
1 package Mojo::SAML::Entity;
2  
3 use Mojo::Base -base;
4  
5 use Mojo::XMLSig;
6 use Mojo::SAML::Names;
7  
8 use Carp ();
9 use Mojo::DOM;
10 use Mojo::File;
11 use Mojo::UserAgent;
12 use Mojo::Util;
13 use Mojo::URL;
14 use Scalar::Util ();
15  
16 my $isa = sub {
17 my ($obj, $class) = @_;
18 Scalar::Util::blessed($obj) && $obj->isa($class);
19 };
20 my %ns = (
21 md => 'urn:oasis:names:tc:SAML:2.0:metadata',
22 ds => 'http://www.w3.org/2000/09/xmldsig#',
23 );
24 my %uses = (
25 encryption => 1,
26 signing => 1,
27 );
28  
29 has entity_id => sub {
30 my $dom = shift->metadata;
31 my $desc = $dom->find('md|EntityDescriptor[entityID]', %ns);
32 Carp::croak 'Multiple EntityDescriptor elements found' if $desc->size > 1;
33 Carp::croak 'No EntityDescriptor elements found' if $desc->size < 1;
34 return $desc->[0]->{entityID};
35 };
36 has role_type => sub { Carp::croak 'role_type is required' };
37 has metadata => sub { Carp::croak 'metadata is required' };
38 has ua => sub { Mojo::UserAgent->new };
39  
40 sub certificate_for {
41 my ($self, $use) = @_;
42 my $attr = ':not([use])';
43 if (defined $use) {
44 Carp::croak "Unknown certificate use $use" unless exists $uses{$use};
45 if ($Mojolicious::VERSION >= 8.42) {
46 $attr = qq!:is([use="$use"], $attr)!;
47 } else {
48 $attr = qq!:matches([use="$use"], $attr)!;
49 }
50 }
51 require Crypt::OpenSSL::X509;
52 my $s = qq!md|KeyDescriptor$attr > ds|KeyInfo > ds|X509Data > ds|X509Certificate!;
53 return undef unless my $elem = $self->role->at($s, %ns);
54 my $cert = Mojo::XMLSig::format_cert($elem->text);
55 return Crypt::OpenSSL::X509->new_from_string($cert);
56 }
57  
58 sub default_id_format {
59 my $self = shift;
60 my $formats = $self->_formats;
61 return $formats->[0];
62 }
63  
64 sub entity {
65 my $self = shift;
66 my $id = Mojo::Util::xml_escape $self->entity_id;
67 return $self->metadata->at(qq<EntityDescriptor[entityID="$id"]>) // Carp::croak 'EntityDescriptor not found';
68 }
69  
70 sub from {
71 my ($self, $arg) = @_;
72 my $method = $arg =~ m{^https?://} ? 'from_url' :
73 $arg =~ m{\s*<} ? 'from_xml' :
74 'from_file';
75 return $self->$method($arg);
76 }
77  
78 sub from_file {
79 my ($self, $file) = @_;
80 $file = Mojo::File->new("$file")
81 unless $file->$isa('Mojo::File');
82 return $self->from_xml(Mojo::Util::decode 'UTF-8', $file->slurp);
83 }
84  
85 sub from_url {
86 my ($self, $url) = @_;
87 my $xml = $self->ua->get($url)->result->body;
88 return $self->from_xml($xml);
89 }
90  
91 sub from_xml {
92 my ($self, $dom) = @_;
93 $dom = Mojo::DOM->new->xml(1)->parse("$dom")
94 unless $dom->$isa('Mojo::DOM');
95 return $self->metadata($dom);
96 }
97  
98 sub location_for {
99 my ($self, $service, $binding) = @_;
100 $binding = Mojo::SAML::Names::binding($binding);
101 my $elem = $self->role->at(qq!md|${service}[Binding="$binding"][Location]!, %ns) || {};
102 return Mojo::URL->new($elem->{Location});
103 }
104  
105 sub name_id_format {
106 my ($self, $format) = @_;
107 my $formats = $self->_formats;
108 return $formats->to_array unless defined $format;
109 return $formats->first(sub{ $_ eq $format }) if $format =~ /:/;
110 $format = qr/urn:oasis:names:tc:SAML:(?:2.0|1.1):nameid-format:\Q$format/;
111 return $formats->first($format);
112 }
113  
114 sub public_key_for {
115 my ($self, $use) = @_;
116 require Crypt::OpenSSL::RSA;
117 my $cert = $self->certificate_for($use);
118 return Crypt::OpenSSL::RSA->new_public_key($cert->pubkey);
119 }
120  
121 sub role {
122 my $self = shift;
123 my $tag = $self->_role_descriptor;
124 return undef unless my $entity = $self->entity;
125 return $self->entity->at("md|$tag", %ns);
126 }
127  
128 sub verify_signature {
129 my ($self, $key) = @_;
130 my $dom = $self->metadata;
131 return undef unless Mojo::XMLSig::has_signature($dom);
132 return Mojo::XMLSig::verify($dom, $key);
133 }
134  
135 sub _formats {
136 my $self = shift;
137 return $self->entity
138 ->find(q!md|IDPSSODescriptor md|NameIDFormat!, %ns)
139 ->map(sub{ Mojo::Util::trim $_->text });
140 }
141  
142 sub _role_descriptor {
143 my $self = shift;
144 my $role = $self->role_type;
145 return 'IDPSSODescriptor' if uc $role eq 'IDP';
146 return 'SPSSODescriptor' if uc $role eq 'SP';
147 return qq!RoleDescriptor[protocolSupportEnumeration~="$role"]!;
148 }
149  
150  
151 1;
152  
153 =head1 NAME
154  
155 Mojo::SAML::Entity - Extract information from an entity
156  
157 =head1 SYNOPSIS
158  
159 =head1 DESCRIPTION
160  
161 L<Mojo::SAML::Entity> is a convenience class for extracting information from Entity entity descriptor metadata.
162 This module is especially fragile and will change as its usefulness is assessed and improved.
163  
164 =head1 ATTRIBUTES
165  
166 L<Mojo::SAML::Entity> inherits all of the attributes from L<Mojo::Base> and implements the following new ones.
167  
168 =head2 entity_id
169  
170 The entity id (C<entityID>) of the entity to be inspected.
171 If the L</metadata> contains only one entity descriptor, it will default to that id.
172 Otherwise, it must be specified manually otherwise it will throw an exception.
173  
174 =head2 metadata
175  
176 The metadata of the entity, as a L<Mojo::DOM> object.
177 Note that there are several methods which can be used to populate this values.
178 Otherwise accessing it without it being set will throw an exception.
179  
180 =head2 role_type
181  
182 Required.
183 The role that this enitty will be used for.
184 Special cases C<IdP> or C<SP> relate to SAML metadata tags.
185 Other values relate to C<protocolSupportEnumeration> RoleDescriptor values.
186  
187 =head2 ua
188  
189 An instance of L<Mojo::UserAgent> used to fetch remote metadata.
190  
191 =head1 METHODS
192  
193 L<Mojo::SAML::Entity> inherits all of the methods from L<Mojo::Base> and implements the following new ones.
194  
195 =head2 certificate_for
196  
197 my $cert = $entity->certificate_for($use);
198  
199 Returns a C<Crypt::OpenSSL::X509> instance for the L</entity> and L</role> and a given use.
200 Note that a certificate without a use will match any use.
201  
202 =head2 default_id_format
203  
204 my $format = $entity->default_id_format;
205  
206 Returns the first nameid format.
207  
208 =head2 entity
209  
210 my $entity = $entity->entity;
211  
212 Get the L<Mojo::DOM> instance for the entity identified by the L</entity_id>.
213 This is used by many other methods for picking the entity information.
214  
215 =head2 from
216  
217 my $entity = Mojo::SAML::Entity->new->from($input);
218  
219 Load L</metadata> from a generic input.
220 Delegates to L</from_file>, L</from_url>, and L</from_xml> depending on the input.
221  
222 =head2 from_file
223  
224 my $entity = Mojo::SAML::Entity->new->from_file($path);
225  
226 Load L</metadata> from a given file.
227 Return the instance, designed to chain with C<new>.
228  
229 =head2 from_url
230  
231 my $entity = Mojo::SAML::Entity->new->from_url($url);
232  
233 Load L</metadata> from a given url using the L</ua>.
234 Return the instance, designed to chain with C<new>.
235  
236 =head2 from_xml
237  
238 my $entity = Mojo::SAML::Entity->new->from_xml($xml);
239  
240 Load L</metadata> from a given string.
241 Return the instance, designed to chain with C<new>.
242  
243 =head2 location_for
244  
245 my $url = $entity->location_for($service, $binding);
246  
247 Extract a L<Mojo::URL> for the L</entity> and L</role>'s given service and binding.
248 The binding may be shortend in a manner that can be fully qualified via L<Mojo::SAML::Names/binding>.
249  
250 =head2 name_id_format
251  
252 $format = $entity->name_id_format($format);
253  
254 Return the nameid format for the L</entity> if the nameid format given is accepted.
255 The format may be shortend in a manner that can be fully qualified via L<Mojo::SAML::Names/nameid_format>.
256  
257 =head2 public_key_for
258  
259 my $pub = $entity->public_key_for($use);
260  
261 A wrapper for L</certificate_for> which returns a L<Crypt::OpenSSL::RSA> public key instance for the certificate.
262  
263 =head2 role
264  
265 Get the L<Mojo::DOM> instance for the element identified by the L</role_type>.
266 This is used by many other methods for picking the role information.
267  
268 =head2 verify_signature
269  
270 my $verified = $entity->verify_signature;
271 my $verified = $entity->verify_signature($pub);
272  
273 Verify the metadata file's signature, either against itself or against a passed in public key.
274 Returns undef if no signature is found or a boolean signifying verification.
275