Sign and Verify

The XBRLQuery core supports the ability to sign and later verify a compiled taxonomy document. This allows you to distribute a taxonomy while allowing a recipient to verify the taxonomy is unchanged and created by you not someone else.

Public/Private key pair

A taxonomy could be hashed using a hash algorithm like SHA256 and the hash made available. A recipient will then be able to hash the taxonomy and find out if their hash is the same as the provided hash. But with such a simple mechanism there is nothing to prevent a third party changing the taxonomy and generating a new hash.

Much better is to use a private/public key pair. Using a private/public key pair allows a taxonomy file to be signed with a private key and then verified using the public key. Because in the private/public pair scheme only the public key needs to be released and the same hash cannot be generated with only the private key a recipient can be sure the file was hashed by the owner of the private key. The public key can also be an X.509 certificate which contains information about the certificate author, information only the author can put there.

Get a key pair

The first thing to is generate a key pair. There are many ways to do this. One is to use an on-line service that will provide the two components you can save into a file. Another is to generate a certificate and export the private key. The certificate will act as the public key.

Sign a taxonomy file

The example code below shows how to sign a taxonomy file. The

require 'XBRL.php'

$private_key = "...appropriate path...";
$signer = new \XBRL_Signer();

$taxonomy_file = "my_taxononmy.zip";
$signature = $signer->sign_taxonomy( $taxonomy_file , $private_key );

The $taxonomy_file parameter of the sign_taxonomy function can be a reference to a taxonomy file or the contents of a taxonomy file as a string. If the parameter is a file, the file is updated with the new signature (replacing any previous signature) and it returns TRUE. If the parameter is a string the response is the string signed.

The $private_key parameter can be a file reference to a private key PEM file or a string containing the private key.

Verify a signed taxonomy file

A recipient can verify the authenticity of a taxonomy by using the verify_taxonomy function.

The example code below shows how to sign a taxonomy file.

require 'XBRL.php'

$public_key = "...appropriate path...";
$signer = new \XBRL_Signer();

$taxonomy_file = "my_taxononmy.zip";
$verified = $signer->verify_taxonomy( $taxonomy_file , $public_key);

The $taxonomy_file parameter of the sign_taxonomy function can be a reference to a taxonomy file or the contents of a taxonomy file as a string.

The $public_keyparameter can be a file reference to a private key PEM file or a string containing the public key.

The result will be TRUE or FALSE.

If there are issue that prevent the file being verified, such as the public key being invalid or the taxonomy file does not exist then an exception will be thrown and the exception will contain information about the issue.