diff --git a/README.adoc b/README.adoc index 595ac4b..56eecb8 100644 --- a/README.adoc +++ b/README.adoc @@ -1,23 +1,20 @@ pdf-simple-sign =============== -:compact-option: 'pdf-simple-sign' is a simple PDF signer intended for documents produced by -the Cairo library. As such, it currently comes with some restrictions: - - * the document may not have any forms or signatures already, as they would be - overwritten - * the document may not employ cross-reference streams, or must constitute - a hybrid-reference file at least - -The signature is attached to the first page and has no appearance. +the Cairo library, GNU troff, ImageMagick, or similar. I don't aim to extend the functionality any further. The project is fairly self-contained and it should be easy to grasp and change to suit to your needs. +Documentation +------------- +See the link:pdf-simple-sign.adoc[man page] for information about usage. +The rest of this README will concern itself with externalities. + Building -------- -Build dependencies: Meson, a C++11 compiler, pkg-config + +Build dependencies: Meson, Asciidoctor, a C++11 compiler, pkg-config + Runtime dependencies: libcrypto (OpenSSL 1.1 API) $ git clone https://git.janouch.name/p/pdf-simple-sign.git @@ -30,15 +27,6 @@ In addition to the C++ version, also included is a native Go port: $ go get janouch.name/pdf-simple-sign/cmd/pdf-simple-sign -Usage ------ - - $ ./pdf-simple-sign document.pdf document.signed.pdf KeyAndCerts.p12 password - -If the signature doesn't fit within the default reservation of 4 kibibytes, -you might need to adjust it using the `-r` option, or throw out any unnecessary -intermediate certificates. - Contributing and Support ------------------------ Use https://git.janouch.name/p/pdf-simple-sign to report bugs, request features, diff --git a/meson.build b/meson.build index ec6c73b..57be9e1 100644 --- a/meson.build +++ b/meson.build @@ -10,3 +10,14 @@ cryptodep = dependency('libcrypto') executable('pdf-simple-sign', 'pdf-simple-sign.cpp', install : true, dependencies : cryptodep) + +asciidoctor = find_program('asciidoctor') +foreach page : ['pdf-simple-sign'] + custom_target('manpage for ' + page, + input: page + '.adoc', output: page + '.1', + command: [asciidoctor, '-b', 'manpage', + '-a', 'release-version=' + meson.project_version(), + '@INPUT@', '-o', '@OUTPUT@'], + install: true, + install_dir: join_paths(get_option('mandir'), 'man1')) +endforeach diff --git a/pdf-simple-sign.adoc b/pdf-simple-sign.adoc new file mode 100644 index 0000000..4bc3227 --- /dev/null +++ b/pdf-simple-sign.adoc @@ -0,0 +1,79 @@ +pdf-simple-sign(1) +================== +:doctype: manpage +:manmanual: pdf-simple-sign Manual +:mansource: pdf-simple-sign {release-version} + +Name +---- +pdf-simple-sign - a simple PDF signer + +Synopsis +-------- +*pdf-simple-sign* [_OPTION_]... _INPUT.pdf_ _OUTPUT.pdf_ _KEY-PAIR.p12_ _PASSWORD_ + +Description +----------- +'pdf-simple-sign' is a simple PDF signer intended for documents produced by +the Cairo library, GNU troff, ImageMagick, or similar. As such, it currently +comes with some restrictions: + + * the document may not have any forms or signatures already, as they would be + overwritten, + * the document may not employ cross-reference streams, or must constitute + a hybrid-reference file at least. + +The key and certificate pair is accepted in the PKCS#12 format. The _PASSWORD_ +must be supplied on the command line, and may be empty if it is not needed. + +The signature is attached to the first page and has no appearance. + +If signature data don't fit within the default reservation of 4 kibibytes, +you might need to adjust it using the *-r* option, or throw out any unnecessary +intermediate certificates. + +Options +------- +*-r* _RESERVATION_, *--reservation*=_RESERVATION_:: + Set aside _RESERVATION_ amount of bytes for the resulting signature. + Feel free to try a few values in a loop. The program itself has no + conceptions about the data, so it can't make accurate predictions. + +*-h*, *--help*:: + Display a help message and exit. + +*-V*, *--version*:: + Output version information and exit. + +Examples +-------- +Create a self-signed certificate, make a document containing the current date, +sign it and verify the attached signature: + + $ openssl req -newkey rsa:2048 -subj "/CN=Test" -nodes + -keyout key.pem -x509 -out cert.pem 2>/dev/null + $ openssl pkcs12 -inkey key.pem -in cert.pem \ + -export -passout pass:test -out key-cert.p12 + $ date | groff -T pdf > test.pdf + $ pdf-simple-sign test.pdf test.signed.pdf key-pair.p12 "" + $ pdfsig test.signed.pdf + Digital Signature Info of: test.signed.pdf + Signature #1: + - Signer Certificate Common Name: Test + - Signer full Distinguished Name: CN=Test + - Signing Time: Sep 05 2020 19:41:22 + - Signing Hash Algorithm: SHA-256 + - Signature Type: adbe.pkcs7.detached + - Signed Ranges: [0 - 6522], [14716 - 15243] + - Total document signed + - Signature Validation: Signature is Valid. + - Certificate Validation: Certificate issuer isn't Trusted. + +Reporting bugs +-------------- +Use https://git.janouch.name/p/pdf-simple-sign to report bugs, request features, +or submit pull requests. + +See also +-------- +*openssl*(1), *pdfsig*(1)