/ 
Authen-NZRealMe-1.23
River stage zero No dependents
/ Authen::NZRealMe::XMLEnc

NAME

Authen::NZRealMe::XMLEnc - XML encryption/decryption

DESCRIPTION

This module implements the subset of http://www.w3.org/2001/04/xmlenc# required to interface with the New Zealand RealMe Login service using SAML 2.0 messaging. In particular, this is used for decrypting the contents of the EncryptedAssertion element in the SAMLResponse parameter of an HTTP-POST from the IdP.

SYNOPSIS

my $decrypter = Authen::NZRealMe->class_for('xml_encrypter')->new(
    pub_cert_file => $self->signing_cert_pathname,
    key_file      => $path_to_private_key_file,
);

my $xml = $decrypter->decrypt_encrypted_data_elements($xml);

METHODS

new( )

Constructor. Generally called indirectly via the "resolve_posted_assertion" in Authen::NZRealMe::ServiceProvider method, which does so like this:

Authen::NZRealMe->class_for('xml_encrypter')->new( options );

Options are passed in as key => value pairs.

For decryption, the Service Provider's RSA signing private key must be passed to the constructor using either the key_text or the key_file option. This key is used to decrypt the random key used by the block cipher to encrypt the assertion.

In normal use (consuming assertions from the RealMe service), this module is never called upon to perform encryption. It does include an implementation of encryption for use by the test suite. When creating an encrypted assertion, two rounds of encryption are performed. First, an AES key is generated at random and used by the block cipher to encrypt the assertion. Next, the AES key is encrypted using the Service Provider's RSA public key and the result is included along with the encrypted assertion. See the test suite for more details.

decrypt_encrypted_data_elements( $xml )

Takes an XML document (as a string) and returns a modified version (also as a string) in which all <EncryptedData> elements are replaced with the unencrypted document fragment.

encrypt_one_element

Currently only needed by the test suite, which calls it like this:

my $encrypted_xml = $encrypter->encrypt_one_element($signed_xml,
    algorithm => 'xenc_aes128cbc',
    target_id => $target_id,
);

Returns a new XML string in which one element from the supplied XML document has been replaced with an <EncryptedData> element.

id_attr

An accessor method for the attribute name used by encrypt_one_element to find the target element to be encrypted. The default name is 'ID', and can be overriden by passing a new value for the 'id_attr' option to the constructor.

key_text

An accessor for the PEM-encoded text used to instantiate an RSA private key object for decryption. The value can be supplied directly using the 'key_text' argument to the constructor, or indirectly with the 'key_file' argument.

pub_cert_text

An accessor for the PEM-encoded text used to instantiate an X509 certificate which in turn is used to create an RSA public key object for encryption. The value can be supplied directly using the 'pub_cert_text' argument to the constructor, or indirectly with the 'pub_cert_file' argument.

pub_key_text

An accessor for the PEM-encoded text used to instantiate an RSA public key object for encryption. The value can be supplied directly using the 'pub_key_text' argument to the constructor, or indirectly with the 'pub_cert_text' or 'pub_cert_file' arguments.

register_encryption_algorithm

Used at module-load-time to register handler methods for each supported encryption algorithm - i.e.: the method is called once per algorithm. A sub-class which added support for addition algorithms would need to ensure that this routine is called for each.

rsa_private_key

Accessor method which returns a Crypt::OpenSSL::RSA private key object using the key_text method.

rsa_public_key

Accessor method which returns a Crypt::OpenSSL::RSA public key object using the pub_key_text method.

SUPPORTED ALGORITHMS

rsa15 - RSAES-PKCS1-v1_5

Used only to encrypt/decrypt the random key which in turn is used by the block cipher to encrypt the XML element data. This is used by the old RealMe service to encrypt the random key.

aes128cbc - AES128-CBC

This is the oold supported block cipher used for the encryption/decryption of XML elements. Whilst it is recognised that use of this cipher is not recommended due to concerns about its security, it is the cipher used by the RealMe service to encrypt SAML assertions.

rsa_oaep_mgf1p - RSA-OAEP-MGF1P

Used only to encrypt/decrypt the random key which in turn is used by the block cipher to encrypt the XML element data. This is used by the new RealMe service to encrypt the random key.

aes256cbc - AES256-CBC

This is the supported block cipher used for the encryption/decryption of XML elements. This is the cipher used by the new RealMe service to encrypt SAML assertions.

SEE ALSO

See Authen::NZRealMe for documentation index.

LICENSE AND COPYRIGHT

Copyright (c) 2010-2022 Enrolment Services, New Zealand Electoral Commission

Written by Grant McLean <grant@catalyst.net.nz>

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.