projects/sencrypt

changeset 1:f0ceb0ad20e7 version-1

Add manpage
author Guido Berhoerster <guido+sencrypt@berhoerster.name>
date Thu Jan 30 00:00:13 2014 +0100 (2014-01-30)
parents 73af139d1a94
children b1d7f4dd26fa
files Makefile README docbook-update-source-data.xsl sencrypt.1.xml
line diff
     1.1 --- a/Makefile	Tue Jan 28 19:23:16 2014 +0100
     1.2 +++ b/Makefile	Thu Jan 30 00:00:13 2014 +0100
     1.3 @@ -41,15 +41,36 @@
     1.4  PAX :=		pax
     1.5  GZIP :=		gzip
     1.6  SED :=		sed
     1.7 +XSLTPROC :=	xsltproc
     1.8 +DOCBOOK5_MANPAGES_STYLESHEET =	http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl
     1.9 +
    1.10 +define generate-manpage-rule =
    1.11 +%.$(1): %.$(1).xml
    1.12 +	$$(XSLTPROC) \
    1.13 +	    --xinclude \
    1.14 +	    --stringparam package $$(PACKAGE) \
    1.15 +	    --stringparam version $$(VERSION)\
    1.16 +	    docbook-update-source-data.xsl $$< | \
    1.17 +	    $$(XSLTPROC) \
    1.18 +	    --xinclude \
    1.19 +	    $$(DOCBOOK5_MANPAGES_FLAGS) \
    1.20 +	    --output $$@ \
    1.21 +	    $$(DOCBOOK5_MANPAGES_STYLESHEET) \
    1.22 +	    -
    1.23 +endef
    1.24  
    1.25  DESTDIR ?=
    1.26  prefix ?=	/usr/local
    1.27  bindir ?=	$(prefix)/bin
    1.28  datadir ?=	$(prefix)/share
    1.29 +mandir ?=	$(datadir)/man
    1.30  
    1.31  HAVE_ERR_H ?=	1
    1.32  
    1.33  OBJS =		sencrypt.o
    1.34 +MANPAGES =	$(PACKAGE).1 $(DECRYPT_ALIAS).1
    1.35 +DOCBOOK5_MANPAGES_FLAGS =	--stringparam man.authors.section.enabled 0 \
    1.36 +				--stringparam man.copyright.section.enabled 0
    1.37  
    1.38  ifeq ($(HAVE_ERR_H),0)
    1.39    OBJS +=	err.o
    1.40 @@ -59,7 +80,7 @@
    1.41  
    1.42  .PHONY: all clean clobber dist install
    1.43  
    1.44 -all: $(PACKAGE)
    1.45 +all: $(PACKAGE) $(MANPAGES)
    1.46  
    1.47  $(PACKAGE): XCPPFLAGS :=	-DOPENSSL_LOAD_CONF
    1.48  ifeq ($(HAVE_ERR_H),1)
    1.49 @@ -71,6 +92,8 @@
    1.50  $(PACKAGE): $(OBJS)
    1.51  	$(LINK.o) $^ $(LDLIBS) -o $@
    1.52  
    1.53 +$(foreach section,1 2 3 4 5 6 7 8 9,$(eval $(call generate-manpage-rule,$(section))))
    1.54 +
    1.55  %.o: %.c
    1.56  	$(MAKEDEPEND.c) $< | $(SED) -f deps.sed >$*.d
    1.57  	$(COMPILE.c) -o $@ $<
    1.58 @@ -78,9 +101,13 @@
    1.59  install:
    1.60  	$(INSTALL.exec) $(PACKAGE) "$(DESTDIR)$(bindir)/$(PACKAGE)"
    1.61  	ln -f $(PACKAGE) "$(DESTDIR)$(bindir)/$(DECRYPT_ALIAS)"
    1.62 +	for manpage in $(MANPAGES); do \
    1.63 +	    $(INSTALL.data) $${manpage} \
    1.64 +	        "$(DESTDIR)$(mandir)/man$${manpage##*.}/$${manpage##*/}"; \
    1.65 +	done
    1.66  
    1.67  clean:
    1.68 -	rm -f $(PACKAGE) $(OBJS)
    1.69 +	rm -f $(PACKAGE) $(OBJS) $(MANPAGES)
    1.70  
    1.71  clobber: clean
    1.72  	rm -f $(patsubst %.o,%.d,$(OBJS))
     2.1 --- a/README	Tue Jan 28 19:23:16 2014 +0100
     2.2 +++ b/README	Thu Jan 30 00:00:13 2014 +0100
     2.3 @@ -16,9 +16,9 @@
     2.4  ------------------
     2.5  
     2.6  sencrypt requires a POSIX:2004 compatible operating system, and needs GNU make,
     2.7 -GNU or BSD install, and the OpenSSL library to be installed. It has been tested
     2.8 -on Linux distributions, FreeBSD, Solaris and Illumos-derived distributions,
     2.9 -UnixWare, and OpenServer.
    2.10 +GNU or BSD install, the xsltproc tool from libxml2 and the OpenSSL library to
    2.11 +be installed. It has been tested on Linux distributions, FreeBSD, Solaris and
    2.12 +Illumos-derived distributions, UnixWare, and OpenServer.
    2.13  
    2.14  License
    2.15  -------
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/docbook-update-source-data.xsl	Thu Jan 30 00:00:13 2014 +0100
     3.3 @@ -0,0 +1,29 @@
     3.4 +<?xml version="1.0"?>
     3.5 +<xsl:stylesheet
     3.6 +  version="1.0"
     3.7 +  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     3.8 +  xmlns:db="http://docbook.org/ns/docbook"
     3.9 +  xmlns="http://docbook.org/ns/docbook"
    3.10 +  exclude-result-prefixes="xsl db">
    3.11 +
    3.12 +  <xsl:param name="package" select="''" />
    3.13 +  <xsl:param name="version" select="''" />
    3.14 +
    3.15 +  <xsl:template match="db:refmeta/db:refmiscinfo[@class = 'source' or
    3.16 +    @class = 'version']"/>
    3.17 +
    3.18 +  <xsl:template match="db:refmeta">
    3.19 +    <xsl:copy>
    3.20 +      <xsl:apply-templates/>
    3.21 +      <refmiscinfo class="source"><xsl:value-of select="$package"/></refmiscinfo>
    3.22 +      <refmiscinfo class="version"><xsl:value-of select="$version"/></refmiscinfo>
    3.23 +    </xsl:copy>
    3.24 +  </xsl:template>
    3.25 +
    3.26 +  <xsl:template match="@*|node()">
    3.27 +    <xsl:copy>
    3.28 +      <xsl:apply-templates select="@*|node()"/>
    3.29 +    </xsl:copy>
    3.30 +  </xsl:template>
    3.31 +
    3.32 +</xsl:stylesheet>
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/sencrypt.1.xml	Thu Jan 30 00:00:13 2014 +0100
     4.3 @@ -0,0 +1,244 @@
     4.4 +<?xml version="1.0"?>
     4.5 +<!--
     4.6 +
     4.7 +Copyright (C) 2014 Guido Berhoerster <guido+sencrypt@berhoerster.name>
     4.8 +
     4.9 +Permission is hereby granted, free of charge, to any person obtaining
    4.10 +a copy of this software and associated documentation files (the
    4.11 +"Software"), to deal in the Software without restriction, including
    4.12 +without limitation the rights to use, copy, modify, merge, publish,
    4.13 +distribute, sublicense, and/or sell copies of the Software, and to
    4.14 +permit persons to whom the Software is furnished to do so, subject to
    4.15 +the following conditions:
    4.16 +
    4.17 +The above copyright notice and this permission notice shall be included
    4.18 +in all copies or substantial portions of the Software.
    4.19 +
    4.20 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    4.21 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    4.22 +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    4.23 +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    4.24 +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    4.25 +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    4.26 +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    4.27 +
    4.28 +-->
    4.29 +<refentry xmlns="http://docbook.org/ns/docbook" xml:lang="en">
    4.30 +  <info>
    4.31 +    <author>
    4.32 +      <personname>
    4.33 +        <firstname>Guido</firstname>
    4.34 +        <surname>Berhoerster</surname>
    4.35 +      </personname>
    4.36 +      <email>guido+sencrypt@berhoerster.name</email>
    4.37 +      <personblurb/>
    4.38 +    </author>
    4.39 +    <date>21 January, 2014</date>
    4.40 +  </info>
    4.41 +  <refmeta>
    4.42 +    <refentrytitle>sencrypt</refentrytitle>
    4.43 +    <manvolnum>1</manvolnum>
    4.44 +    <refmiscinfo class="source"/>
    4.45 +    <refmiscinfo class="version"/>
    4.46 +    <refmiscinfo class="manual">User Commands</refmiscinfo>
    4.47 +  </refmeta>
    4.48 +  <refnamediv>
    4.49 +    <refname>sencrypt</refname>
    4.50 +    <refname>sdecrypt</refname>
    4.51 +    <refpurpose>encrypt and decrypt data</refpurpose>
    4.52 +  </refnamediv>
    4.53 +  <refsynopsisdiv>
    4.54 +    <cmdsynopsis>
    4.55 +      <command>sencrypt</command>
    4.56 +      <arg choice="req">
    4.57 +        <option>-l</option>
    4.58 +      </arg>
    4.59 +    </cmdsynopsis>
    4.60 +    <cmdsynopsis>
    4.61 +      <command>sencrypt</command>
    4.62 +      <arg choice="opt">
    4.63 +        <option>-v</option>
    4.64 +      </arg>
    4.65 +      <arg choice="req">
    4.66 +        <option>-a</option>
    4.67 +        <replaceable>algorithm</replaceable>
    4.68 +      </arg>
    4.69 +      <arg choice="opt">
    4.70 +        <option>-k</option>
    4.71 +        <replaceable>key_file</replaceable>
    4.72 +      </arg>
    4.73 +      <arg choice="opt">
    4.74 +        <option>-i</option>
    4.75 +        <replaceable>input_file</replaceable>
    4.76 +      </arg>
    4.77 +      <arg choice="opt">
    4.78 +        <option>-o</option>
    4.79 +        <replaceable>output_file</replaceable>
    4.80 +      </arg>
    4.81 +    </cmdsynopsis>
    4.82 +    <cmdsynopsis>
    4.83 +      <command>sdecrypt</command>
    4.84 +      <arg choice="req">
    4.85 +        <option>-l</option>
    4.86 +      </arg>
    4.87 +    </cmdsynopsis>
    4.88 +    <cmdsynopsis>
    4.89 +      <command>sdecrypt</command>
    4.90 +      <arg choice="opt">
    4.91 +        <option>-v</option>
    4.92 +      </arg>
    4.93 +      <arg choice="req">
    4.94 +        <option>-a</option>
    4.95 +        <replaceable>algorithm</replaceable>
    4.96 +      </arg>
    4.97 +      <arg choice="opt">
    4.98 +        <option>-k</option>
    4.99 +        <replaceable>key_file</replaceable>
   4.100 +      </arg>
   4.101 +      <arg choice="opt">
   4.102 +        <option>-i</option>
   4.103 +        <replaceable>input_file</replaceable>
   4.104 +      </arg>
   4.105 +      <arg choice="opt">
   4.106 +        <option>-o</option>
   4.107 +        <replaceable>output_file</replaceable>
   4.108 +      </arg>
   4.109 +    </cmdsynopsis>
   4.110 +  </refsynopsisdiv>
   4.111 +  <refsect1>
   4.112 +    <title>Description</title>
   4.113 +    <para>The <command>sencrypt</command> utility encrypts data and the
   4.114 +    <command>sdecrypt</command> utility decrypts data using the specified
   4.115 +    algorithm. A key file must be a regular file and have the exact size of the
   4.116 +    desired key length, its content will be used verbatim as the key. If no key
   4.117 +    file is specified <command>sencrypt</command> or
   4.118 +    <command>sdecrypt</command> will ask for a passphrase and use that together
   4.119 +    with a salt to derive a key using the PBKDF2 key derivation function. If no
   4.120 +    input file is specfified, the input will be read from stdin. If no output
   4.121 +    file is specfied, the output will be written to stdout. The input and
   4.122 +    output file may be identical, in which case the content of the input file
   4.123 +    is replaced with the output after successful encryption or decryption. The
   4.124 +    algorithm used for encrypting data is not saved and needs to be explicitly
   4.125 +    specified when decrypting data.</para>
   4.126 +    <para><command>sencrypt</command> and <command>sdecrypt</command> are
   4.127 +    portable and compatible reimplementations of the <command>encrypt</command>
   4.128 +    and <command>decrypt</command> utilities in Solaris/Illumos-based operating
   4.129 +    systems.</para>
   4.130 +  </refsect1>
   4.131 +  <refsect1>
   4.132 +    <title>Options</title>
   4.133 +    <para>The following options are supported:</para>
   4.134 +    <variablelist>
   4.135 +      <varlistentry>
   4.136 +        <term>
   4.137 +          <option>-l</option>
   4.138 +        </term>
   4.139 +        <listitem>
   4.140 +          <para>List the available algorithms and supported key lengths and
   4.141 +          exit.</para>
   4.142 +        </listitem>
   4.143 +      </varlistentry>
   4.144 +      <varlistentry>
   4.145 +        <term>
   4.146 +          <option>-a</option>
   4.147 +          <replaceable>algorithm</replaceable>
   4.148 +        </term>
   4.149 +        <listitem>
   4.150 +          <para>Use the specified algorithm.</para>
   4.151 +        </listitem>
   4.152 +      </varlistentry>
   4.153 +      <varlistentry>
   4.154 +        <term>
   4.155 +          <option>-k</option>
   4.156 +          <replaceable>key_file</replaceable>
   4.157 +        </term>
   4.158 +        <listitem>
   4.159 +          <para>Read key data from specified key file. Key size requirements
   4.160 +          depend on the selected algorithm.</para>
   4.161 +        </listitem>
   4.162 +      </varlistentry>
   4.163 +      <varlistentry>
   4.164 +        <term>
   4.165 +          <option>-i</option>
   4.166 +          <replaceable>input_file</replaceable>
   4.167 +        </term>
   4.168 +        <listitem>
   4.169 +          <para>Read the input from the specified file.</para>
   4.170 +        </listitem>
   4.171 +      </varlistentry>
   4.172 +      <varlistentry>
   4.173 +        <term>
   4.174 +          <option>-o</option>
   4.175 +          <replaceable>output_file</replaceable>
   4.176 +        </term>
   4.177 +        <listitem>
   4.178 +          <para>Write the output to the specified file.</para>
   4.179 +        </listitem>
   4.180 +      </varlistentry>
   4.181 +      <varlistentry>
   4.182 +        <term>
   4.183 +          <option>-v</option>
   4.184 +        </term>
   4.185 +        <listitem>
   4.186 +          <para>Ignored for compatibility with <command>encrypt</command> and
   4.187 +          <command>decrypt</command>.</para>
   4.188 +        </listitem>
   4.189 +      </varlistentry>
   4.190 +    </variablelist>
   4.191 +  </refsect1>
   4.192 +  <refsect1>
   4.193 +    <title>Examples</title>
   4.194 +    <example>
   4.195 +      <title>Encrypt a file with the AES algorithm</title>
   4.196 +      <para>The following example encrypts a file with the AES algorithm:</para>
   4.197 +      <screen>
   4.198 +$ sencrypt -a aes -i secret.txt -o secret.aes
   4.199 +      </screen>
   4.200 +    </example>
   4.201 +    <example>
   4.202 +      <title>Decrypt a file in-place</title>
   4.203 +      <para>The following example decrypts a file in-place:</para>
   4.204 +      <screen>
   4.205 +$ sdecrypt -a 3des -i data.bin -o data.bin
   4.206 +      </screen>
   4.207 +    </example>
   4.208 +    <example>
   4.209 +      <title>Encrypt a file using a key file</title>
   4.210 +      <para>The following example generates a key file with 512 bits of random
   4.211 +      data and uses it to encrypt a file:</para>
   4.212 +      <screen>
   4.213 +$ dd if=/dev/urandom of=key.bin bs=64 count=1
   4.214 +$ sencrypt -a arcfour -k key.bin -i secret.txt -o secret.rc4
   4.215 +      </screen>
   4.216 +    </example>
   4.217 +    <example>
   4.218 +      <title>Pipe data trough encrypt in order to make a remote encrypted
   4.219 +      backup</title>
   4.220 +      <para>The following example creates an archive in the tar format,
   4.221 +      encrypts it and sends it to a remote location via
   4.222 +      <abbrev>SSH</abbrev>:</para>
   4.223 +      <screen>
   4.224 +$ pax -w -x ustar /home | sencrypt -a aes -k backup-key.bin |\
   4.225 +    ssh backuphost 'cat > home.tar'
   4.226 +      </screen>
   4.227 +    </example>
   4.228 +  </refsect1>
   4.229 +  <refsect1>
   4.230 +    <title>Exit Status</title>
   4.231 +    <para>The following exit values are returned:</para>
   4.232 +    <variablelist>
   4.233 +      <varlistentry>
   4.234 +        <term>0</term>
   4.235 +        <listitem>
   4.236 +          <para>Command successfully executed.</para>
   4.237 +        </listitem>
   4.238 +      </varlistentry>
   4.239 +      <varlistentry>
   4.240 +        <term>&gt; 0</term>
   4.241 +        <listitem>
   4.242 +          <para>An error has occured.</para>
   4.243 +        </listitem>
   4.244 +      </varlistentry>
   4.245 +    </variablelist>
   4.246 +  </refsect1>
   4.247 +</refentry>