File: README.md

DsigSdk

• PHP SDK of XML Digital Signature recomendation
• based on the [XSD] schema

and provide

• dto's for all element(type)s in [XSD] * src/Dto * with getters and setters, no other logic
• parse of XML into dto(s) * src/XMLParse/DsigParser::parse
• write of dto(s) to XML string / DomNode * src/XMLWrite/DsigWriter::write
• logic aid support * src/Impl * common : convenient salt, base64, hex, pack etc unility methods * Hash : message digest support * HmacHash : message hmac digest support * OpenSSL : encryption/decryption support * Misc

For help finding a good PHP cryptography library, please review * Choosing the Right Cryptography Library for your PHP Project: A Guide

Usage, parse XML

To parse an Dsig (Signature root) XML file (using XMLReader) :

<?php
namespace Kigkonsult\DsigSdk;
use Kigkonsult\DsigSdk\XMLParse\DsigParser;

$dsig = DsigParser::factory()->parse( 
    file_get_contents( 'DsigFile.xml' )
);

$signedInfo = $dsig->getsignedInfo();
...

The XML parser save the XMLreader node properties (baseURI, localName, name, namespaceURI, prefix) for each XML (Dto) element as 'XMLattributes' as well as XML attributes (xmlns, xmlns:*, schemaLocation), if set (more info below).

'any' [XSD] elements are accepted as 'Anytype' object instances (more info below, 'AnyType').

Usage, build up structure

To build up dsig structure:

<?php
namespace Kigkonsult\DsigSdk;
use Kigkonsult\DsigSdk\Dto\AnyType;
use Kigkonsult\DsigSdk\Dto\CanonicalizationMethodType;
use Kigkonsult\DsigSdk\Dto\KeyInfoType;
use Kigkonsult\DsigSdk\Dto\SignedInfoType;
use Kigkonsult\DsigSdk\Dto\SignatureType;
use Kigkonsult\DsigSdk\Dto\SignatureValueType;

$dsig = SignatureType::factory()
    ->setSignedInfo( 
        SignedInfoType::factory()
            ->setCanonicalizationMethod(
                CanonicalizationMethodType::factory()
                    ->setAlgorithm( SignatureType::MINICANONICAL )
                    ->setAny( [
                        AnyType::factory()
                            ->setElementName( 'nonSchemaElement1')
                            ->setAttributes( [
                                'id' => '12345' 
                                ] )
                             ->setContent( 'Lr1mKGxP7VAgMB...' ),
                        AnyType::factory()
                            ->setElementName( 'nonSchemaElement2')
                            ->setSubElements( [
                                AnyType::factory()
                                    ->setElementName( 'nonSchemaElement3')
                                    ->setContent( 'Lr1mKGxP7VAgMB...' ),
                            ] )
                        ]
                    )
            )
    )
    ->setSignatureValue(
        SignatureValueType::factory()
            ->setSignatureValueType( 'vgGZnRlm8...' )
    )
    ->setKeyInfo(
        KeyInfoType::factory()
            ->setKeyInfoType( [
                [                 // one set of elements
                    [             // element
                        SignatureType::X509DATA => 
                            X509DataType::factory()
                                ->setX509Certificate( ... )
                    ],
                ],
        ] )
    )
    ->setObject(
        ...
    )
    ...

XML attributes

You can set (single 'element') XMLattribute using

$dsig->setXMLAttribut( <key>, <value> );

To set (ex. prefix) and 'propagate' down in hierarchy:

$dsig->setXMLAttribut( SignatureType::PREFIX, <value>, true );

You can remove (single 'element') XMLattribute using

$dsig->unsetXMLAttribut( <key> );

To unset (ex. prefix) and 'propagate' down in hierarchy:

$dsig->unsetXMLAttribut( SignatureType::PREFIX, true );

To fetch and iterate over XMLAttributes

foreach( $dsig->getXMLAttributes() as $key => $value {
    ...
}

Anytype

Anytype object instances are used for 'any' [XSD] elements. The element name are stored and fetched with

$anytype->setElementName( <name> );

$anytypeName = $anytype->getElementName();

The 'any' [XSD] element attributes may include XML attributes.

The AnyType attributes are stored and fetched as array.

$anytype->setAttributes( [ <key> => <value> ] );

foreach( $anytype->getAttributes() as $key => $value {
    ...
}

Note, an AnyType instance may have * content * type string, * AnyType::setContent() * AnyType::getContent()

or * sub-elements type array [AnyType] * AnyType::setSubElements() * AnyType::getSubElements()

but not both.

Usage, output as XML

DsigSdk uses XMLWriter creating output.

$XMLstring = DsigWriter::factory()->write( $dsig );

The XMLwriter adds for each element * element name with prefix, if exists XMLattribute xmlns, xmlns: and schemaLocation, if exists.

Usage, output as DomNode

$domNode = DsigWriter::factory()->write( $dsig, true );

Info

For class structure and architecture, please review * the [XSD] * docs/Dsig.png class design * the src/DsigLoader directory

You may find convenient constants in - src/DsigInterface - src/XMLAttributesInterface

For base64Encode/base64Decode/hash support, please review src/Impl/Impl.md

Installation

[Composer]

From the Command Line:

composer require kigkonsult/dsigsdk

In your composer.json:

{
    "require": {
        "kigkonsult/dsigsdk": "dev-master"
    }
}

Acquire access

namespace Kigkonsult\DsigSdk;
...
include 'vendor/autoload.php';

Run tests

cd pathToSource/DsigSdk
vendor/bin/phpunit

Or

Download and acquire..

namepace Kigkonsult\DsigSdk;
...
include 'pathToSource/DsigSdk/autoload.php';

Support

For support, please use [Github]/issues.

License

This project is licensed under the LGPLv3 License

[Composer]:https://getcomposer.org/ [Github]:https://github.com/iCalcreator/dsigsdk/issues [http://www.w3.org/2000/09/xmldsig#]:http://www.w3.org/2000/09/xmldsig# [XSD]:https://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsd