← Back to branch summary

~ubuntu-branches/ubuntu/hardy/openswan/hardy-updates

« back to all changes in this revision

Viewing changes to lib/libopenswan/keyblobtoid.3.xml

  • Committer: Bazaar Package Importer
  • Author(s): Rene Mayrhofer
  • Date: 2005-01-27 16:10:11 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20050127161011-idgybmyz3vwhpfiq
Tags: 2.3.0-2
http://bugs.debian.org/292458
http://bugs.debian.org/291143
Urgency HIGH due to security issue and problems with build-deps in sarge.
* Fix the security issue. Please see
  http://www.idefense.com/application/poi/display?id=190&
      type=vulnerabilities&flashstatus=false
  for more details. Thanks to Martin Schulze for informing me about
  this issue.
  Closes: #292458: Openswan XAUTH/PAM Buffer Overflow Vulnerability
* Added a Build-Dependency to lynx.
  Closes: #291143: openswan: FTBFS: Missing build dependency.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/libopenswan/keyblobtoid.3.xml
 
1
<?xml version="1.0" encoding="ISO-8859-1"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 
3
                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 
4
<!-- lifted from troff+man by doclifter -->
 
5
<refentry>
 
6
<refmeta>
 
7
<refentrytitle>IPSEC_KEYBLOBTOID</refentrytitle>
 
8
<manvolnum>3</manvolnum>
 
9
<refmiscinfo class='date'>25 March 2002</refmiscinfo>
 
10
</refmeta>
 
11
<refnamediv id='name'>
 
12
<refname>ipsec keyblobtoid</refname>
 
13
<refname>splitkeytoid</refname>
 
14
<refpurpose>generate key IDs from RSA keys</refpurpose>
 
15
</refnamediv>
 
16
<!-- body begins here -->
 
17
<refsynopsisdiv id='synopsis'>
 
18
<funcsynopsis>
 
19
<funcsynopsisinfo>
 
20
#include &lt;freeswan.h&gt;
 
21
 
 
22
</funcsynopsisinfo>
 
23
<funcprototype>
 
24
<funcdef>size_t <function>keyblobtoid</function></funcdef>
 
25
    <paramdef>const unsigned char * <parameter>blob</parameter></paramdef>
 
26
    <paramdef>size_t <parameter>bloblen</parameter></paramdef>
 
27
    <paramdef>char * <parameter>dst</parameter></paramdef>
 
28
    <paramdef>size_t <parameter>dstlen</parameter></paramdef>
 
29
</funcprototype>
 
30
<funcsynopsisinfo>
 
31
 
 
32
</funcsynopsisinfo>
 
33
<funcprototype>
 
34
<funcdef>size_t <function>splitkeytoid</function></funcdef>
 
35
    <paramdef>const unsigned char * <parameter>e</parameter></paramdef>
 
36
    <paramdef>size_t <parameter>elen</parameter></paramdef>
 
37
    <paramdef>const unsigned char * <parameter>m</parameter></paramdef>
 
38
    <paramdef>size_t <parameter>mlen</parameter></paramdef>
 
39
    <paramdef>char * <parameter>dst</parameter></paramdef>
 
40
    <paramdef>size_t <parameter>dstlen</parameter></paramdef>
 
41
</funcprototype>
 
42
</funcsynopsis>
 
43
</refsynopsisdiv>
 
44
 
 
45
 
 
46
<refsect1 id='description'><title>DESCRIPTION</title>
 
47
<para><emphasis remap='I'>Keyblobtoid</emphasis>
 
48
and
 
49
<function>splitkeytoid</function>
 
50
generate
 
51
key IDs
 
52
from RSA keys,
 
53
for use in messages and reporting,
 
54
writing the result to
 
55
<varname role='parameter'>dst</varname>.
 
56
A
 
57
<emphasis remap='I'>key ID</emphasis>
 
58
is a short ASCII string identifying a key;
 
59
currently it is just the first nine characters of the base64
 
60
encoding of the RFC 2537/3110 &ldquo;byte blob&rdquo; representation of the key.
 
61
(Beware that no finite key ID can be collision-proof:
 
62
there is always some small chance of two random keys having the
 
63
same ID.)</para>
 
64
 
 
65
<para><emphasis remap='I'>Keyblobtoid</emphasis>
 
66
generates a key ID from a key which is already in the form of an
 
67
RFC 2537/3110 binary key
 
68
<varname role='parameter'>blob</varname>
 
69
(encoded exponent length, exponent, modulus).</para>
 
70
 
 
71
<para><emphasis remap='I'>Splitkeytoid</emphasis>
 
72
generates a key ID from a key given in the form of a separate
 
73
(binary) exponent
 
74
<varname role='parameter'>e</varname>
 
75
and modulus
 
76
<varname role='parameter'>m</varname>.</para>
 
77
 
 
78
<para>The
 
79
<varname role='parameter'>dstlen</varname>
 
80
parameter of either
 
81
specifies the size of the
 
82
<varname role='parameter'>dst</varname>
 
83
parameter;
 
84
under no circumstances are more than
 
85
<varname role='parameter'>dstlen</varname>
 
86
bytes written to
 
87
<varname role='parameter'>dst</varname>.
 
88
A result which will not fit is truncated.
 
89
<emphasis remap='I'>Dstlen</emphasis>
 
90
can be zero, in which case
 
91
<varname role='parameter'>dst</varname>
 
92
need not be valid and no result is written,
 
93
but the return value is unaffected;
 
94
in all other cases, the (possibly truncated) result is NUL-terminated.
 
95
The
 
96
<emphasis remap='I'>freeswan.h</emphasis>
 
97
header file defines a constant
 
98
<emphasis remap='B'>KEYID_BUF</emphasis>
 
99
which is the size of a buffer large enough for worst-case results.</para>
 
100
 
 
101
<para>Both functions return
 
102
<literal>0</literal>
 
103
for a failure, and otherwise
 
104
always return the size of buffer which would 
 
105
be needed to
 
106
accommodate the full conversion result, including terminating NUL;
 
107
it is the caller's responsibility to check this against the size of
 
108
the provided buffer to determine whether truncation has occurred.</para>
 
109
 
 
110
<para>With keys generated by
 
111
<citerefentry><refentrytitle>ipsec_rsasigkey</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 
112
the first two base64 digits are always the same,
 
113
and the third carries only about one bit of information.
 
114
It's worse with keys using longer fixed exponents,
 
115
e.g. the 24-bit exponent that's common in X.509 certificates.
 
116
However, being able to relate key IDs to the full
 
117
base64 text form of keys by eye is sufficiently useful that this
 
118
waste of space seems justifiable.
 
119
The choice of nine digits is a compromise between bulk and
 
120
probability of collision.</para>
 
121
</refsect1>
 
122
 
 
123
<refsect1 id='see_also'><title>SEE ALSO</title>
 
124
<para>RFC 3110,
 
125
<emphasis remap='I'>RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS)</emphasis>,
 
126
Eastlake, 2001
 
127
(superseding the older but better-known RFC 2537).</para>
 
128
</refsect1>
 
129
 
 
130
<refsect1 id='diagnostics'><title>DIAGNOSTICS</title>
 
131
<para>Fatal errors are:
 
132
key too short to supply enough bits to construct a complete key ID
 
133
(almost certainly indicating a garbage key);
 
134
exponent too long for its length to be representable.</para>
 
135
</refsect1>
 
136
 
 
137
<refsect1 id='history'><title>HISTORY</title>
 
138
<para>Written for the FreeS/WAN project by Henry Spencer.</para>
 
139
</refsect1>
 
140
</refentry>
 
141