202 lines
4.7 KiB
Perl
202 lines
4.7 KiB
Perl
package Mail::DKIM::ARC::Seal;
|
|
use strict;
|
|
use warnings;
|
|
our $VERSION = '1.20230212'; # VERSION
|
|
# ABSTRACT: represents a ARC-Seal header
|
|
|
|
# Copyright 2017 FastMail Pty Ltd. All Rights Reserved.
|
|
# Bron Gondwana <brong@fastmailteam.com>
|
|
#
|
|
# This program is free software; you can redistribute it and/or
|
|
# modify it under the same terms as Perl itself.
|
|
|
|
use base 'Mail::DKIM::ARC::MessageSignature';
|
|
|
|
|
|
sub new {
|
|
my $class = shift;
|
|
my %prms = @_;
|
|
my $self = {};
|
|
bless $self, $class;
|
|
|
|
$self->instance( $prms{'Instance'} ) if exists $prms{'Instance'};
|
|
$self->algorithm( $prms{'Algorithm'} || 'rsa-sha256' );
|
|
$self->signature( $prms{'Signature'} );
|
|
$self->canonicalization( $prms{'Method'} ) if exists $prms{'Method'};
|
|
$self->chain( $prms{'Chain'} || 'none' );
|
|
$self->domain( $prms{'Domain'} );
|
|
$self->selector( $prms{'Selector'} );
|
|
$self->timestamp(
|
|
defined $prms{'Timestamp'} ? $prms{'Timestamp'} : time() );
|
|
$self->expiration( $prms{'Expiration'} ) if defined $prms{'Expiration'};
|
|
$self->key( $prms{'Key'} ) if defined $prms{'Key'};
|
|
|
|
return $self;
|
|
}
|
|
|
|
sub body_hash {
|
|
|
|
# Not defined for ARC-Seal
|
|
return;
|
|
}
|
|
|
|
sub DEFAULT_PREFIX {
|
|
return 'ARC-Seal:';
|
|
}
|
|
|
|
|
|
sub chain {
|
|
my $self = shift;
|
|
if (@_) {
|
|
my $cv = shift;
|
|
die "INVALID chain value $cv"
|
|
unless grep { $cv eq $_ } qw(none fail pass);
|
|
$self->set_tag( 'cv', $cv );
|
|
}
|
|
return $self->get_tag('cv');
|
|
}
|
|
|
|
|
|
sub canonicalization {
|
|
return ( 'seal', 'seal' );
|
|
}
|
|
|
|
|
|
1;
|
|
|
|
__END__
|
|
|
|
=pod
|
|
|
|
=encoding UTF-8
|
|
|
|
=head1 NAME
|
|
|
|
Mail::DKIM::ARC::Seal - represents a ARC-Seal header
|
|
|
|
=head1 VERSION
|
|
|
|
version 1.20230212
|
|
|
|
=head1 CONSTRUCTORS
|
|
|
|
=head2 new() - create a new signature from parameters
|
|
|
|
my $signature = Mail::DKIM::ARC::Seal->new(
|
|
[ Algorithm => 'rsa-sha256', ]
|
|
[ Signature => $base64, ]
|
|
[ Domain => 'example.org', ]
|
|
[ Instance => 1, ]
|
|
[ Chain => 'none', ] # none|fail|pass
|
|
[ Query => 'dns', ]
|
|
[ Selector => 'alpha', ]
|
|
[ Timestamp => time(), ]
|
|
[ Expiration => time() + 86400, ]
|
|
);
|
|
|
|
The ARC-Seal is similar to a DKIM signature but with the following changes:
|
|
|
|
https://tools.ietf.org/html/draft-ietf-dmarc-arc-protocol-06
|
|
|
|
5.1.1.1. Tags in the ARC-Seal Header Field Value
|
|
|
|
The following tags are the only supported tags for an ARC-Seal field.
|
|
All of them MUST be present. Unknown tags MUST be ignored and do not
|
|
affect the validity of the header.
|
|
|
|
o a = hash algorithm; syntax is the same as the "a=" tag defined in
|
|
Section 3.5 of [RFC6376];
|
|
|
|
o b = digital signature; syntax is the same as the "b=" tag defined
|
|
in Section 3.5 of [RFC6376];
|
|
|
|
o cv = chain validation status: valid values:
|
|
|
|
* 'none' = no pre-existing chain;
|
|
|
|
* 'fail' = the chain as received does not or can not validate; or
|
|
|
|
* 'pass' = valid chain received.
|
|
|
|
o d = domain for key; syntax is the same as the "d=" tag defined in
|
|
Section 3.5 of [RFC6376];
|
|
|
|
o i = "instance" or sequence number; monotonically increasing at
|
|
each "sealing" entity, beginning with '1', see Section 5.1.1.1.1
|
|
regarding the valid range
|
|
|
|
o s = selector for key; syntax is the same as the "s=" tag defined
|
|
in Section 3.5 of [RFC6376];
|
|
|
|
o t = timestamp; syntax is the same as the "t=" tag defined in
|
|
Section 3.5 of [RFC6376].
|
|
|
|
=head2 chain() - get or set the chain parameter (cv=) field
|
|
|
|
This must be one of "pass", "fail" or "none". For a chain to be valid,
|
|
the very first (i=1) seal MUST be cv=none, and all further seals MUST be
|
|
cv=pass.
|
|
|
|
=head2 instance() - get or set the signing instance (i=) field
|
|
|
|
my $i = $signature->instance;
|
|
|
|
Instances must be integers less than 1024 according to the spec.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<Mail::DKIM::Signature> for DKIM-Signature headers
|
|
|
|
L<Mail::DKIM::ARC::MessageSignature> for ARC-Message-Signature headers
|
|
|
|
=head1 AUTHORS
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
Jason Long <jason@long.name>
|
|
|
|
=item *
|
|
|
|
Marc Bradshaw <marc@marcbradshaw.net>
|
|
|
|
=item *
|
|
|
|
Bron Gondwana <brong@fastmailteam.com> (ARC)
|
|
|
|
=back
|
|
|
|
=head1 THANKS
|
|
|
|
Work on ensuring that this module passes the ARC test suite was
|
|
generously sponsored by Valimail (https://www.valimail.com/)
|
|
|
|
=head1 COPYRIGHT AND LICENSE
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
Copyright (C) 2013 by Messiah College
|
|
|
|
=item *
|
|
|
|
Copyright (C) 2010 by Jason Long
|
|
|
|
=item *
|
|
|
|
Copyright (C) 2017 by Standcore LLC
|
|
|
|
=item *
|
|
|
|
Copyright (C) 2020 by FastMail Pty Ltd
|
|
|
|
=back
|
|
|
|
This library is free software; you can redistribute it and/or modify
|
|
it under the same terms as Perl itself, either Perl version 5.8.6 or,
|
|
at your option, any later version of Perl 5 you may have available.
|
|
|
|
=cut
|