DSTU4145 Agent
Usage
Sign and encrypt file for tax office email gate.
Ready to send to tax office email gate. Would include data, signuture, transport headers with email to send response to among other things:
node index.js --sign --crypt otrimano.cer \
--tsp all \
--key Key-6.dat:password \
--cert cert.sign.der --cert cert.cryp.der \
--input zvit.xml --output zvit.xml.sign.enc \
--email ilya.muromec@gmail.com
Note: name of input file AND name of email attachment matters for processing server.
Filename format for tax office is following:
'15 01 3225000000 F01 033 05 1 00 0000001 5 12 2015 15 01.xml'
tax period code --^
tax period length in months --^
tax year -- ^
code of tax office and region again --^---^
^-- document increment id
^-- document amendment version
^-- document state
^-- for code and version
^-- your tax id
^-- code of tax office
^-- code of tax region
Sign file (czo.gov.ua/verify)
When --no-tax
option is specified in command line, both transport header and UA_SIGN1
prefix would be ommited, producing raw ASN1 file in CMS (almosrt) format. Email option is ignored in this mode, as no transport header is writte. Makes most sense to sign contracts and such:
node index.js --sign \
--key Key-6.dat:password \
--cert cert.sign.der \
--input text.pdf --output text.pdf.p7s \
--no-tax \
--tsp all
Example commandline for privatbank keys:
node index.js --sign \
--key pb_1234567890.jks:password \
--input text.pdf --output text.pdf.p7s \
--no-tax \
--tsp all
Write detached signature
When --detached
option is specified in command line, resulting file would only contain signuture. Signed data would not be included. Makes most sense with --no-tax
present and `--email`` ommited. This is not compatible with tax office email gate:
node index.js --sign \
--key Key-6.dat:password \
--cert cert.sign.der \
--input zvit.xml --output zvit.xml.sign \
--detached --no-tax
Load key from jks store (privatbank)
Since version 0.4.40 it's possible to use use jks files with agent. Since jks file format contains number of keys at the same time, with first key being electronic stamp (not a personal key), agent has support of --role
option in commandline. Possible values are:
- personal - certificate belongs to natural person and has no record of any corporate entity;
- fop (fizychna osoba pidpryjemets) - certificate belongs to natural person registered as private entrepreneur, technically this means that personal code (10, 9 or 8 digit DRFO) matches corporate code (EDRPOU);
- director - certificate either belongs to FOP or natural person that can sign on behalf of corporate entity, technicall this means that corporate code either matches drfo or drfo code is present and corporate code does not belong to natural person;
- stamp - certificate belongs to corporate entity itself, not natural person;
- other - personal code is present but does not match corporate code (relaxed version of director);
- exact personal code (either DRFO or passport number for religious people) to match. should be 10, 9 or 8 characters long
Example:
node index.js --sign \
--key Key-6.dat:password \
--cert cert.sign.der \
--input zvit.xml --output zvit.xml.sign \
--detached --no-tax \
--role stamp
Load key from nonencrypted store
node index.js --sign \
--key Key-6.raw \
--cert cert.sign.der \
--input zvit.xml --output zvit.xml.sign
Encrypt only
Notice, that both certificates are specified. This is implementation requirement, not really needed in code.
node index.js --crypt otrimano.cer \
--key Key-6.dat:password \
--cert cert.sign.der --cert cert.cryp.der \
--input zvit.xml --output zvit.xml.sign.enc
Unwrap
To unwrap and decrypt incoming messages, use --decrypt
command-line switch. Notice that certificate is not required here.
node index.js --decrypt \
--key fop_acsk.raw.der \
--input incoming.encrypted \
--output clear \
--tsp all \
--ocsp strict \
--ca_path CACertificates.p7b
TSP
To add secure timestamp, use --tsp
command-line switch. Secure timestamp is mandatory for long-term storage since November 7th 2018.
Aceepts a value --tsp signature
--tsp content
or --tsp all
. Options --tsp
and --tsp content
are equivalent.
When specified as --tsp all
, agent would include both content and signature timestamps. If specified when parsing the message, timestamps
would be checked against document and TSP certificate and dates would be included in the output.
node index.js --sign \
--tsp signature \
--key Key-6.raw \
--cert cert.sign.der \
--input zvit.xml --output zvit.xml.sign
CA list
List of certificate authorities is only used as a list of preloaded certificates, mainly for TSP verification. Get one from https://id.gov.ua/verify-widget/v20200922/Data/CACertificates.p7b
(or older version).
Note: for some unknown reason, id.gov.ua rejectes download requests made with Wget user agent. Setting empty user agent works just fine: wget -O - 'https://id.gov.ua/verify-widget/v20200922/Data/CACertificates.p7b' --header='User-Agent: '
If CA list is supplied, all signed messages are verified against CA list and failures would result in unwrap error
OCSP
When CA list is supplied it's also possible to verify signer certificate validity through OCSP. OCSP cmdline argument could be either unspecified --ocsp
, --ocsp strict
or --ocsp lax
. In strict mode, all OCSP failures, even transient ones, would result in unwrap error. Argument specified without value defaults to srict
. In lax mode network errors (including mailformed and tampered responses) would be reported but would not result in unwrap error.
Agent mode
Signer can operate as out-of-process agent. One process would load key storage and listen to local socket, while other would pass data to be signed to it.
Example:
node index.js --agent \
--key Key-6.dat:password \
--cert cert.ipp.sign --cert cert.ipp.cryp &
node index.js --connect \
--sign \
--input zvit.xml --output zvit.xml.sign
Agent mode is available for encrypt and unwrap operations as well:
# start agent as specified above
node index.js --decrypt --connect --input encrypted.pkcs7 --output clear
Key unwrapper
Normaly keys are stored inside encrypted file called Key-6.dat that requires password to be decrypted every time it is being loaded.
However you can remove this protection from and store raw version of file.
node index.js --unprotect --key Key-6.dat:password --output fop_acsk.raw.der
node index.js --unprotect --key Key-6.dat:password > fop_acsk.raw.pem
Notice that without --output
argument, private is outputed to standard output in PEM form.
Notes
Starting from jkurwa version 0.4.20, agent can read documents created by "ME.DOC" software.
Reference
This app is able to sign and encrypt pre-crafted tax reports. Tax report format specifications:
- http://opz.at.ua/index/struktura_fajla_xml/0-57 -- Filename structure and file general file format
- http://sfs.gov.ua/data/material/000/006/58768/Forms1.htm -- Tax form specification
- http://github.com/muromec/taxes-ua -- Tax difference calculator