Commit 44ddc891 authored by Rick van Rein's avatar Rick van Rein
Browse files

Man pages for kip(1) and many kipxxx_yyy(3) functions

Resolves #7 as far as achievable:
  * kip(1)
  * kipdata_up(3) and kipdata_down(3)
  * kipctx_open(3) and kipctx_close(3)
  * kipkey_generate(3) and kipkey_algorithm(3) and kipdata_random(3)
  * kipkey_tomap(3) and kipkey_frommap(3)
  * kipsum_sign(3) and kipsum_verify(3)
parent 4f754a94
......@@ -65,6 +65,7 @@ include_directories (${CMAKE_CURRENT_SOURCE_DIR}/include ${MIT-krb5_INCLUDE_DIRS
add_subdirectory (lib)
add_subdirectory (test)
add_subdirectory (src)
add_subdirectory (doc)
#
# Building
......
# Relative to here
set(doc_SRCS
keyformats.md
kip-keytabs.md
kip-service-protocol.graphml
kip-service-protocol.pdf
kip.md
)
# Relative to top-level
set(license_SRCS
${CMAKE_SOURCE_DIR}/README.MD
${CMAKE_SOURCE_DIR}/PYPELINE.MD
# README
# INSTALL
# TODO
)
# Relative to here
set(man1_SRCS
kip
)
set(man3_SRCS
kipctx_open
kipctx_close
kipdata_up
kipdate_down
kipkey_generate
kipkey_algorithm
kipdata_random
kipkey_tomap
kipkey_frommap
#TODO# kipkey_fromservice
#TODO# kipkey_toservice
#TODO# kipkey_fromkeytab
kipsum_sign
kipkey_verify
#TODO# kipsum_append
#TODO# kipsum_start
)
set(man8_SRCS
)
install(FILES ${doc_SRCS} ${license_SRCS} DESTINATION ${CMAKE_INSTALL_DATADIR}/doc/tlspool/)
foreach(m ${man1_SRCS})
install(FILES man/${m}.man DESTINATION ${CMAKE_INSTALL_MANDIR}/man1/ RENAME ${m}.1)
endforeach()
foreach(m ${man3_SRCS})
if (EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/man/${m}.man)
set (last_manpage man/${m}.man)
endif()
install(FILES ${last_manpage} DESTINATION ${CMAKE_INSTALL_MANDIR}/man3/ RENAME ${m}.3)
endforeach()
foreach(m ${man8_SRCS})
install(FILES man/${m}.man DESTINATION ${CMAKE_INSTALL_MANDIR}/man8/ RENAME ${m}.8)
endforeach()
.TH KIP 1 "March 2019" "ARPA2.net" "System Management Commands"
.SH NAME
kip \- Encryption through the Keyful Identity Protocol
.SH SYNOPSIS
.B kip
.BR up | down
.I infile outfile
.SH DESCRIPTION
.PP
To protect data, they must be encrypted to a key.
Recipients then recover the key and, using that,
recover the protected content. With public-key
systems such as
.BR gpg (1)
there is a need to know the recipients' keys before
data can be protected. With
.BR kip "(1)"
however, a fresh key can be generated and made available
to the intended recipients when they ask for it. This
simplifies the work involved in encryption, at the expense
of a little extra work during decryption.
.PP
The method used is founded on authentication. The
fresh key is packaged together with an access control list
(ACL), and encrypted using a KIP Service. Only this KIP Service
is then able to recover the key, which it will only reveal
the key to authenticated identities on the ACL.
.PP
This is a trade-off. One needs to rely on the KIP Service
to be online, and when the key is discarded it is needed
again during later decryption attempts. On the other hand,
no more credentials are needed than authentication credentials.
Particularly pleasant to use is a single-signon system such
as Kerberos.
.PP
The command
.B kip up
is used to "kip up" the content to a level fit for distribution,
and
.B kip down
is used to reverse the process after retrieval.
In both cases, the
.I infile
is read and the
.I outfile
is written. We generally use the
.B .kip
extension on documents that have been "kipped up".
Such a document is between 2% and 10% larger
than the original, because no compression is performed. The
decrypted content of the KIP document is integrity protected
with a secure hash signed under the encryption key. This means
that only parties holding this key are able to alter the
document without distorting the integrity check.
.SH KIP SERVICE
The KIP Service runs as a stateless protocol, except for a
few aspects:
.IP *
The KIP Service has access to a key table, holding its
master key. A separate master key is usually created for
every domain that is supported.
.IP *
The KIP Service performs authentication through SASL, and
to do that it needs access to a SASL backend.
.PP
There is no technical need for a KIP Service to ever store the
keys that pass through it. The KIP protocol will never pass
the encrypted content through the KIP Service, only the keys
are handled by it. These two aspects make the KIP Service a
very light-weight service.
.SH AUTHOR
.PP
Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project.
.SH "REPORTING BUGS"
.PP
Please use our issue track for reporting bugs. It can be
found online, at
.IR https://gitlab.com/arpa2/kip/issues .
.SH COPYRIGHT
.PP
Copyright \(co 2019 Rick van Rein, ARPA2.net.
.PP
ARPA2 is funded from InternetWide.org, which in turns receives donations
from various funding sources with an interest in a private and secure
Internet that gives users control over their online presence. This particular
project is part of ARPA2 Mail & Reservoir, funded by SIDNfonds.
.SH "SEE ALSO"
.IR gpg "(1), " smime "(1ssl), " openssl "(1ssl), " ktutil "(1)."
.PP
Online resources may be found on the project home page,
.IR http://https://gitlab.com/arpa2/kip .
.TH KIPCTX_OPEN 3 "March 2019" "ARPA2.net" "Library Calls"
.SH NAME
kipctx_open, kipctx_close \- Contexts for the Keyful Identity Protocol
.SH SYNOPSIS
.B #include <stdbool.h>
.sp
.B #include <arpa2/kip.h>
.sp
.B bool kipctx_open (kipt_ctx *\fIout_ctx\fB);
.sp
.B void kipctx_close (kipt_ctx \fIctx\fB);
.br
.SH DESCRIPTION
.PP
These functions open and close a context handle for
working with KIP. The context handle is needed for
all other KIP functions, and is used as a storage
structure. All collected storage is cleaned up
when the context is closed.
.PP
Do not use a KIP context simultaneously in multiple
threads. They are designed to be owned by one thread
at a time. Functions exist to move keying material
between contexts in binary form.
.SH RETURN VALUE
The open function returns \fBtrue\fR on success, or
\fBfalse\fR with \fBerrno\fR set. Note that the
functions use the \fIcom_err\fR system and define
their own \fBKIPERR_xxx\fR error codes.
.SH AUTHOR
.PP
Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project.
.SH "REPORTING BUGS"
.PP
Please use our issue track for reporting bugs. It can be
found online, at
.IR https://gitlab.com/arpa2/kip/issues .
.SH COPYRIGHT
.PP
Copyright \(co 2019 Rick van Rein, ARPA2.net.
.PP
ARPA2 is funded from InternetWide.org, which in turns receives donations
from various funding sources with an interest in a private and secure
Internet that gives users control over their online presence. This particular
project is part of ARPA2 Mail & Reservoir, funded by SIDNfonds.
.SH "SEE ALSO"
.IR kip "(1), " kipdata_up "(3), " kipdata_down "(3),
.IR " kipdata_random "(3), " kipkey_generate "(3)."
.PP
Online resources may be found on the project home page,
.IR http://https://gitlab.com/arpa2/kip .
.TH KIPCTX_OPEN 3 "March 2019" "ARPA2.net" "Library Calls"
.SH NAME
kipdata_up, kipdata_down \- KIP data up and down
.SH SYNOPSIS
.B #include <stdbool.h>
.br
.B #include <stdint.h>
.sp
.B #include <arpa2/kip.h>
.sp
.B bool kipdata_up (kipt_ctx ctx, kipt_keyid key,
.RS
.B uint8_t *\fIclear\fB, uint32_t \fIclearsz\fB,
.B uint8_t *\fIout_mud\fB, uint32_t \fImax_mudsz\fB,
.B uint32_t *\fIout_mudsz\fB);
.RE
.sp
.B bool kipdata_down (kipt_ctx ctx, kipt_keyid key,
.RS
.B uint8_t *\fImud\fB, uint32_t \fImudsz\fB,
.B uint8_t *\fIout_clear\fB, uint32_t \fImax_clearsz\fB,
.B uint32_t *\fIout_clearsz\fB);
.RE
.br
.SH DESCRIPTION
.PP
These functions "kip up" and "kip down" a block
of data. Kipping up comes down to encryption
with a checksum, kipping down comes down to
decryption and an integrity check.
.PP
The \fIclear\fR arguments indicate the plaintext
information, the \fImud\fR arguments represent
the unreadable binary data. The latter is safe
to transport, or at least as safe as the protection
of the \fIkey\fR that was used.
.PP
The \fIkey\fR is obtained from other function calls,
and generally several build up in a KIP context.
.PP
If an output buffer must be allocated but no size
is available, it is possible to invoke these
functions with the \fImax_xxxsz\fR set to zero.
The functions then return an error code
\fBKIPERR_OUTPUT_SIZE\fR and store the required
size in the \fIout_xxxsz\fR, which is also used
on successful return.
.SH RETURN VALUE
These functions return \fBtrue\fR on success, or
\fBfalse\fR with \fBerrno\fR set. Note that the
functions use the \fIcom_err\fR system and define
their own \fBKIPERR_xxx\fR error codes.
.PP
.SH AUTHOR
.PP
Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project.
.SH "REPORTING BUGS"
.PP
Please use our issue track for reporting bugs. It can be
found online, at
.IR https://gitlab.com/arpa2/kip/issues .
.SH COPYRIGHT
.PP
Copyright \(co 2019 Rick van Rein, ARPA2.net.
.PP
ARPA2 is funded from InternetWide.org, which in turns receives donations
from various funding sources with an interest in a private and secure
Internet that gives users control over their online presence. This particular
project is part of ARPA2 Mail & Reservoir, funded by SIDNfonds.
.SH "SEE ALSO"
.IR kip "(1), " kipctx_open "(3), " kipctx_close "(3),
.IR " kipkey_generate "(3), " kipdata_random "(3)."
.PP
Online resources may be found on the project home page,
.IR http://https://gitlab.com/arpa2/kip .
.TH KIPCTX_OPEN 3 "March 2019" "ARPA2.net" "Library Calls"
.SH NAME
kipkey_generate, kipkey_algorithm, kipdata_random \- KIP key and data generation.
.SH SYNOPSIS
.B #include <stdbool.h>
.br
.B #include <stdint.h>
.sp
.B #include <arpa2/kip.h>
.sp
.B bool kipkey_generate (kipt_ctx \fIctx\fB, kipt_alg \fIalg\fB,
.RS
.B kipt_keynr \fIin_keynr\fB,
.B kipt_keyid *\fIout_keyid\fB);
.RE
.sp
.B bool kipkey_algorithm (kipt_ctx \fIctx\fB, kipt_keyid \fIkeyid\fB,
.RS
.B kipt_alg *\fIout_alg\fB);
.RE
.sp
.B bool kipdata_random (kipt_ctx \fIctx\fB,
.RS
.B uint32_t \fIlen_target\fB, uint8_t *\fIout_target\fB);
.RE
.br
.SH DESCRIPTION
.PP
These functions can be used to generate key material
and data within a KIP context. The function
.BR kipkey_generate (3)
creates a fresh KIP key and stores it under the
context. The algorithm is selected with the
\fIalg\fR argument, which is a code of a Kerberos5
encryption type as registered by IANA. The function
.B kipkey_algorithm (3)
retrieves this algorithm for a given \fIkeyid\fR.
The function
.B kipdata_random (3)
is not principally related to key generation, but it
is often used around the same time, namely when starting
the work inside a KIP context, to generate a continuous
sequence of random bytes with a pseudo-random generator.
.PP
Keys are identified on the wire a unsigned 32-bit
integer values. These are mostly unique, but KIP does
not enforce this property. Thanks to this leniency,
it is relatively straightforward to merge data sources,
even when keys have the same 32-bit number. KIP uses
the integrity check contained in kipped-up data to
select a key if multiple options exist. The context
however, holds a unique handle for a key in the form
of a \fIkeyid\fR. Key identities are like upgraded
forms of a key number, with a unique value added.
This unique portion is removed when flattening a
key description for use in the wire format.
.PP
Keys are not destroyed until the entire KIP context
is destroyed in a call to
.BR kipctx_close (3).
.SH RETURN VALUE
.PP
These functions return \fBtrue\fR on success, or
\fBfalse\fR with \fBerrno\fR set. Note that the
functions use the \fIcom_err\fR system and define
their own \fBKIPERR_xxx\fR error codes.
.PP
.SH AUTHOR
.PP
Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project.
.SH "REPORTING BUGS"
.PP
Please use our issue track for reporting bugs. It can be
found online, at
.IR https://gitlab.com/arpa2/kip/issues .
.SH COPYRIGHT
.PP
Copyright \(co 2019 Rick van Rein, ARPA2.net.
.PP
ARPA2 is funded from InternetWide.org, which in turns receives donations
from various funding sources with an interest in a private and secure
Internet that gives users control over their online presence. This particular
project is part of ARPA2 Mail & Reservoir, funded by SIDNfonds.
.SH "SEE ALSO"
.IR kip "(1), " kipctx_open "(3), " kipctx_close "(3),
.IR kipkey_tomap "(3), " kipkey_frommap "(3), "
.IR kipkey_toservice "(3), " kipkey_fromservice "(3), "
.IR kipkey_fromkeytab "(3)."
.PP
Online resources may be found on the project home page,
.IR http://https://gitlab.com/arpa2/kip .
.TH KIPCTX_OPEN 3 "March 2019" "ARPA2.net" "Library Calls"
.SH NAME
kipkey_fromkeytab \- KIP keys from Kerberos key tables.
.SH SYNOPSIS
.B #include <stdbool.h>
.br
.B #include <stdint.h>
.sp
.B #include <arpa2/kip.h>
.sp
.B bool kipkey_fromkeytab (kipt_ctx \fIctx\fB, char *\fIopt_ktname\fB,
.RS
.B char *\fI opt_hostname, char *domain,
.B kipt_keynr kvno, kipt_alg enctype,
.B kipt_keyid *out_keyid);
.RE
.sp
.B bool kipkey_frommap (kipt_ctx \fIctx\fB,
.RS
.B uint8_t *\fIkeymud\fB, uint32_t \fIkeymudsz\fB,
.B kipt_keyid *\fIout_mappedkey\fB);
.RE
.br
.SH DESCRIPTION
.PP
These functions allow translation from one key
into another. Even when a kipped up portion of
a document is encrypted to a single key, it is
possible to construct multiple key maps that lead
to that key. This enables a logic "OR" function
in terms of keys that may read that portion of
the document.
.PP
For perfect balance, a logic "AND" function can also be
constructed, by mapping from multiple keys, which
are applied in sequence and which must therefore all
be available to permit access to the key map.
.PP
The function
.BR kipkey_tomap (3)
therefore requires not just a \fIkeyid\fR to map,
but also one or more \fImappingkeyids\fR, whose
number is provided as \fImappingdepth\fR. (In the
simple case where the depth is one, the sequence
of key identities can be a mere pointer to the one
key identity, so no arrays needs to be constructed.)
.PP
The \fImud\fR parameters follow the usual protocol,
including the error code \fBKIPERR_OUTPUT_SIZE\fR
with the output length stored, as always, in the
\fIout_keymudsz\fR to aid in allocation.
.PP
The \fIkeymud\fR should be considered as secure as
the mapping key(s), and can normally be sent over
unprotected wires as far as encryption goes; there
is an issue of authenticity that may be remedied
with other tools.
.PP
If the
.BR kipkey_tomap (3)
exists to "kip up" a key, the mirror function of
"kipping down" this \fIkeymud\fR is the
.BR kipkey_frommap (3)
function.
Take note that key mapping is entirely a local
operation; keys used for mapping must already
be available in the KIP context \fIctx\fR if it
is to work.
.PP
Keys are not destroyed until the entire KIP context
is destroyed in a call to
.BR kipctx_close (3).
.SH RETURN VALUE
.PP
These functions return \fBtrue\fR on success, or
\fBfalse\fR with \fBerrno\fR set. Note that the
functions use the \fIcom_err\fR system and define
their own \fBKIPERR_xxx\fR error codes.
.PP
.SH AUTHOR
.PP
Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project.
.SH "REPORTING BUGS"
.PP
Please use our issue track for reporting bugs. It can be
found online, at
.IR https://gitlab.com/arpa2/kip/issues .
.SH COPYRIGHT
.PP
Copyright \(co 2019 Rick van Rein, ARPA2.net.
.PP
ARPA2 is funded from InternetWide.org, which in turns receives donations
from various funding sources with an interest in a private and secure
Internet that gives users control over their online presence. This particular
project is part of ARPA2 Mail & Reservoir, funded by SIDNfonds.
.SH "SEE ALSO"
.IR kip "(1), " kipctx_open "(3), " kipctx_close "(3),
.IR kipkey_generate "(3),
.IR kipkey_toservice "(3), " kipkey_fromservice "(3), "
.IR kipkey_fromkeytab "(3)."
.PP
Online resources may be found on the project home page,
.IR http://https://gitlab.com/arpa2/kip .
.TH KIPCTX_OPEN 3 "March 2019" "ARPA2.net" "Library Calls"
.SH NAME
kipsum_sign, kipsum_verify \- KIP signing and verification
.SH SYNOPSIS
.B #include <stdbool.h>
.br
.B #include <stdint.h>
.sp
.B #include <arpa2/kip.h>
.sp
.B bool kipsum_sign (kipt_ctx \fIctx\fB,
.RS
.B kipt_sumid \fIsumid_or_keyid\fB, uint32_t \fImax_siglen\fB,
.B uint32_t *\fIout_siglen\fB, uint8_t *\fIout_sig\fB);
.RE
.sp
.B bool kipsum_verify (kipt_ctx \fIctx\fB,
.RS
.B kipt_sumid \fIsumid_or_keyid\fB,
.B uint32_t \fIsiglen\fB, uint8_t *\fIsig\fB);
.RE
.br
.SH DESCRIPTION
.PP
These functions sign a checksum under a
\fIsumid\fR or \fIkeyid\fR, or validate it.
For any key introduced in the KIP context, an
implicit checksum is started. Every successful
call to
.BR kipdata_up (3)
or
.BR kipdata_down (3)
appends the plaintext to the integrity check.
The signature is protected with a key, and this is
considered during verification. The use of the key
is the protection of integrity, because no party
can change the data without invalidating the
checksum, unless they hold the key.
.PP
Checksums are secure hashes, more specifically the
hash algorithm implied by the key used to protect
it. Since this key is already known at the beginning
of the checksum, there is no need to be explicit
about the checksum algorithm. Unlike a MAC, the
entire hash value is included.
.PP
If an output buffer must be allocated but no size
is available, it is possible to invoke these
functions with the \fImax_xxxsz\fR set to zero.
The functions then return an error code
\fBKIPERR_OUTPUT_SIZE\fR and store the required
size in the \fIout_xxxsz\fR, which is also used
on successful return.
.SH RETURN VALUE
These functions return \fBtrue\fR on success, or
\fBfalse\fR with \fBerrno\fR set. Note that the
functions use the \fIcom_err\fR system and define
their own \fBKIPERR_xxx\fR error codes.
.PP
.SH AUTHOR
.PP
Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project.
.SH "REPORTING BUGS"
.PP
Please use our issue track for reporting bugs. It can be
found online, at
.IR https://gitlab.com/arpa2/kip/issues .
.SH COPYRIGHT
.PP
Copyright \(co 2019 Rick van Rein, ARPA2.net.
.PP
ARPA2 is funded from InternetWide.org, which in turns receives donations
from various funding sources with an interest in a private and secure
Internet that gives users control over their online presence. This particular
project is part of ARPA2 Mail & Reservoir, funded by SIDNfonds.
.SH "SEE ALSO"
.IR kip "(1), " kipkey_generate "(3), "
.IR kipkey_frommap "(3), " kipkey_fromservice "(3)."
.PP
Online resources may be found on the project home page,
.IR http://https://gitlab.com/arpa2/kip .
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment