Mercurial > projects > sencrypt

changeset 1:f0ceb0ad20e7 version-1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add manpage
author Guido Berhoerster <guido+sencrypt@berhoerster.name>
date Thu, 30 Jan 2014 00:00:13 +0100
parents 73af139d1a94
children b1d7f4dd26fa
files Makefile README docbook-update-source-data.xsl sencrypt.1.xml
diffstat 4 files changed, 305 insertions(+), 5 deletions(-) [+]
line wrap: on
line diff
--- a/Makefile	Tue Jan 28 19:23:16 2014 +0100
+++ b/Makefile	Thu Jan 30 00:00:13 2014 +0100
@@ -41,15 +41,36 @@
 PAX :=		pax
 GZIP :=		gzip
 SED :=		sed
+XSLTPROC :=	xsltproc
+DOCBOOK5_MANPAGES_STYLESHEET =	http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl
+
+define generate-manpage-rule =
+%.$(1): %.$(1).xml
+	$$(XSLTPROC) \
+	    --xinclude \
+	    --stringparam package $$(PACKAGE) \
+	    --stringparam version $$(VERSION)\
+	    docbook-update-source-data.xsl $$< | \
+	    $$(XSLTPROC) \
+	    --xinclude \
+	    $$(DOCBOOK5_MANPAGES_FLAGS) \
+	    --output $$@ \
+	    $$(DOCBOOK5_MANPAGES_STYLESHEET) \
+	    -
+endef
 
 DESTDIR ?=
 prefix ?=	/usr/local
 bindir ?=	$(prefix)/bin
 datadir ?=	$(prefix)/share
+mandir ?=	$(datadir)/man
 
 HAVE_ERR_H ?=	1
 
 OBJS =		sencrypt.o
+MANPAGES =	$(PACKAGE).1 $(DECRYPT_ALIAS).1
+DOCBOOK5_MANPAGES_FLAGS =	--stringparam man.authors.section.enabled 0 \
+				--stringparam man.copyright.section.enabled 0
 
 ifeq ($(HAVE_ERR_H),0)
   OBJS +=	err.o
@@ -59,7 +80,7 @@
 
 .PHONY: all clean clobber dist install
 
-all: $(PACKAGE)
+all: $(PACKAGE) $(MANPAGES)
 
 $(PACKAGE): XCPPFLAGS :=	-DOPENSSL_LOAD_CONF
 ifeq ($(HAVE_ERR_H),1)
@@ -71,6 +92,8 @@
 $(PACKAGE): $(OBJS)
 	$(LINK.o) $^ $(LDLIBS) -o $@
 
+$(foreach section,1 2 3 4 5 6 7 8 9,$(eval $(call generate-manpage-rule,$(section))))
+
 %.o: %.c
 	$(MAKEDEPEND.c) $< | $(SED) -f deps.sed >$*.d
 	$(COMPILE.c) -o $@ $<
@@ -78,9 +101,13 @@
 install:
 	$(INSTALL.exec) $(PACKAGE) "$(DESTDIR)$(bindir)/$(PACKAGE)"
 	ln -f $(PACKAGE) "$(DESTDIR)$(bindir)/$(DECRYPT_ALIAS)"
+	for manpage in $(MANPAGES); do \
+	    $(INSTALL.data) $${manpage} \
+	        "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \
+	done
 
 clean:
-	rm -f $(PACKAGE) $(OBJS)
+	rm -f $(PACKAGE) $(OBJS) $(MANPAGES)
 
 clobber: clean
 	rm -f $(patsubst %.o,%.d,$(OBJS))
--- a/README	Tue Jan 28 19:23:16 2014 +0100
+++ b/README	Thu Jan 30 00:00:13 2014 +0100
@@ -16,9 +16,9 @@
 ------------------
 
 sencrypt requires a POSIX:2004 compatible operating system, and needs GNU make,
-GNU or BSD install, and the OpenSSL library to be installed. It has been tested
-on Linux distributions, FreeBSD, Solaris and Illumos-derived distributions,
-UnixWare, and OpenServer.
+GNU or BSD install, the xsltproc tool from libxml2 and the OpenSSL library to
+be installed. It has been tested on Linux distributions, FreeBSD, Solaris and
+Illumos-derived distributions, UnixWare, and OpenServer.
 
 License
 -------
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docbook-update-source-data.xsl	Thu Jan 30 00:00:13 2014 +0100
@@ -0,0 +1,29 @@
+<?xml version="1.0"?>
+<xsl:stylesheet
+  version="1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:db="http://docbook.org/ns/docbook"
+  xmlns="http://docbook.org/ns/docbook"
+  exclude-result-prefixes="xsl db">
+
+  <xsl:param name="package" select="''" />
+  <xsl:param name="version" select="''" />
+
+  <xsl:template match="db:refmeta/db:refmiscinfo[@class = 'source' or
+    @class = 'version']"/>
+
+  <xsl:template match="db:refmeta">
+    <xsl:copy>
+      <xsl:apply-templates/>
+      <refmiscinfo class="source"><xsl:value-of select="$package"/></refmiscinfo>
+      <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo>
+    </xsl:copy>
+  </xsl:template>
+
+  <xsl:template match="@*|node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|node()"/>
+    </xsl:copy>
+  </xsl:template>
+
+</xsl:stylesheet>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/sencrypt.1.xml	Thu Jan 30 00:00:13 2014 +0100
@@ -0,0 +1,244 @@
+<?xml version="1.0"?>
+<!--
+
+Copyright (C) 2014 Guido Berhoerster <guido+sencrypt@berhoerster.name>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+<refentry xmlns="http://docbook.org/ns/docbook" xml:lang="en">
+  <info>
+    <author>
+      <personname>
+        <firstname>Guido</firstname>
+        <surname>Berhoerster</surname>
+      </personname>
+      <email>guido+sencrypt@berhoerster.name</email>
+      <personblurb/>
+    </author>
+    <date>21 January, 2014</date>
+  </info>
+  <refmeta>
+    <refentrytitle>sencrypt</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class="source"/>
+    <refmiscinfo class="version"/>
+    <refmiscinfo class="manual">User Commands</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>sencrypt</refname>
+    <refname>sdecrypt</refname>
+    <refpurpose>encrypt and decrypt data</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>sencrypt</command>
+      <arg choice="req">
+        <option>-l</option>
+      </arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>sencrypt</command>
+      <arg choice="opt">
+        <option>-v</option>
+      </arg>
+      <arg choice="req">
+        <option>-a</option>
+        <replaceable>algorithm</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-k</option>
+        <replaceable>key_file</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-i</option>
+        <replaceable>input_file</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-o</option>
+        <replaceable>output_file</replaceable>
+      </arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>sdecrypt</command>
+      <arg choice="req">
+        <option>-l</option>
+      </arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>sdecrypt</command>
+      <arg choice="opt">
+        <option>-v</option>
+      </arg>
+      <arg choice="req">
+        <option>-a</option>
+        <replaceable>algorithm</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-k</option>
+        <replaceable>key_file</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-i</option>
+        <replaceable>input_file</replaceable>
+      </arg>
+      <arg choice="opt">
+        <option>-o</option>
+        <replaceable>output_file</replaceable>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>Description</title>
+    <para>The <command>sencrypt</command> utility encrypts data and the
+    <command>sdecrypt</command> utility decrypts data using the specified
+    algorithm. A key file must be a regular file and have the exact size of the
+    desired key length, its content will be used verbatim as the key. If no key
+    file is specified <command>sencrypt</command> or
+    <command>sdecrypt</command> will ask for a passphrase and use that together
+    with a salt to derive a key using the PBKDF2 key derivation function. If no
+    input file is specfified, the input will be read from stdin. If no output
+    file is specfied, the output will be written to stdout. The input and
+    output file may be identical, in which case the content of the input file
+    is replaced with the output after successful encryption or decryption. The
+    algorithm used for encrypting data is not saved and needs to be explicitly
+    specified when decrypting data.</para>
+    <para><command>sencrypt</command> and <command>sdecrypt</command> are
+    portable and compatible reimplementations of the <command>encrypt</command>
+    and <command>decrypt</command> utilities in Solaris/Illumos-based operating
+    systems.</para>
+  </refsect1>
+  <refsect1>
+    <title>Options</title>
+    <para>The following options are supported:</para>
+    <variablelist>
+      <varlistentry>
+        <term>
+          <option>-l</option>
+        </term>
+        <listitem>
+          <para>List the available algorithms and supported key lengths and
+          exit.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>-a</option>
+          <replaceable>algorithm</replaceable>
+        </term>
+        <listitem>
+          <para>Use the specified algorithm.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>-k</option>
+          <replaceable>key_file</replaceable>
+        </term>
+        <listitem>
+          <para>Read key data from specified key file. Key size requirements
+          depend on the selected algorithm.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>-i</option>
+          <replaceable>input_file</replaceable>
+        </term>
+        <listitem>
+          <para>Read the input from the specified file.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>-o</option>
+          <replaceable>output_file</replaceable>
+        </term>
+        <listitem>
+          <para>Write the output to the specified file.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>
+          <option>-v</option>
+        </term>
+        <listitem>
+          <para>Ignored for compatibility with <command>encrypt</command> and
+          <command>decrypt</command>.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+  <refsect1>
+    <title>Examples</title>
+    <example>
+      <title>Encrypt a file with the AES algorithm</title>
+      <para>The following example encrypts a file with the AES algorithm:</para>
+      <screen>
+$ sencrypt -a aes -i secret.txt -o secret.aes
+      </screen>
+    </example>
+    <example>
+      <title>Decrypt a file in-place</title>
+      <para>The following example decrypts a file in-place:</para>
+      <screen>
+$ sdecrypt -a 3des -i data.bin -o data.bin
+      </screen>
+    </example>
+    <example>
+      <title>Encrypt a file using a key file</title>
+      <para>The following example generates a key file with 512 bits of random
+      data and uses it to encrypt a file:</para>
+      <screen>
+$ dd if=/dev/urandom of=key.bin bs=64 count=1
+$ sencrypt -a arcfour -k key.bin -i secret.txt -o secret.rc4
+      </screen>
+    </example>
+    <example>
+      <title>Pipe data trough encrypt in order to make a remote encrypted
+      backup</title>
+      <para>The following example creates an archive in the tar format,
+      encrypts it and sends it to a remote location via
+      <abbrev>SSH</abbrev>:</para>
+      <screen>
+$ pax -w -x ustar /home | sencrypt -a aes -k backup-key.bin |\
+    ssh backuphost 'cat > home.tar'
+      </screen>
+    </example>
+  </refsect1>
+  <refsect1>
+    <title>Exit Status</title>
+    <para>The following exit values are returned:</para>
+    <variablelist>
+      <varlistentry>
+        <term>0</term>
+        <listitem>
+          <para>Command successfully executed.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>&gt; 0</term>
+        <listitem>
+          <para>An error has occured.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+</refentry>