← 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

  • 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
 
1
.TH IPSEC_KEYBLOBTOID 3 "25 March 2002"
 
2
.\" RCSID $Id: keyblobtoid.3,v 1.5 2004/04/09 18:00:39 mcr Exp $
 
3
.SH NAME
 
4
ipsec keyblobtoid, splitkeytoid \- generate key IDs from RSA keys
 
5
.SH SYNOPSIS
 
6
.B "#include <freeswan.h>
 
7
.sp
 
8
.B "size_t keyblobtoid(const unsigned char *blob,"
 
9
.ti +1c
 
10
.B "size_t bloblen, char *dst, size_t dstlen);"
 
11
.br
 
12
.B "size_t splitkeytoid(const unsigned char *e, size_t elen,"
 
13
.ti +1c
 
14
.B "const unsigned char *m, size_t mlen, char *dst,
 
15
.ti +1c
 
16
.B "size_t dstlen);"
 
17
.SH DESCRIPTION
 
18
.I Keyblobtoid
 
19
and
 
20
.I splitkeytoid
 
21
generate
 
22
key IDs
 
23
from RSA keys,
 
24
for use in messages and reporting,
 
25
writing the result to
 
26
.IR dst .
 
27
A
 
28
.I key ID
 
29
is a short ASCII string identifying a key;
 
30
currently it is just the first nine characters of the base64
 
31
encoding of the RFC 2537/3110 ``byte blob'' representation of the key.
 
32
(Beware that no finite key ID can be collision-proof:
 
33
there is always some small chance of two random keys having the
 
34
same ID.)
 
35
.PP
 
36
.I Keyblobtoid
 
37
generates a key ID from a key which is already in the form of an
 
38
RFC 2537/3110 binary key
 
39
.I blob
 
40
(encoded exponent length, exponent, modulus).
 
41
.PP
 
42
.I Splitkeytoid
 
43
generates a key ID from a key given in the form of a separate
 
44
(binary) exponent
 
45
.I e
 
46
and modulus
 
47
.IR m .
 
48
.PP
 
49
The
 
50
.I dstlen
 
51
parameter of either
 
52
specifies the size of the
 
53
.I dst
 
54
parameter;
 
55
under no circumstances are more than
 
56
.I dstlen
 
57
bytes written to
 
58
.IR dst .
 
59
A result which will not fit is truncated.
 
60
.I Dstlen
 
61
can be zero, in which case
 
62
.I dst
 
63
need not be valid and no result is written,
 
64
but the return value is unaffected;
 
65
in all other cases, the (possibly truncated) result is NUL-terminated.
 
66
The
 
67
.I freeswan.h
 
68
header file defines a constant
 
69
.B KEYID_BUF
 
70
which is the size of a buffer large enough for worst-case results.
 
71
.PP
 
72
Both functions return
 
73
.B 0
 
74
for a failure, and otherwise
 
75
always return the size of buffer which would 
 
76
be needed to
 
77
accommodate the full conversion result, including terminating NUL;
 
78
it is the caller's responsibility to check this against the size of
 
79
the provided buffer to determine whether truncation has occurred.
 
80
.P
 
81
With keys generated by
 
82
.IR ipsec_rsasigkey (3),
 
83
the first two base64 digits are always the same,
 
84
and the third carries only about one bit of information.
 
85
It's worse with keys using longer fixed exponents,
 
86
e.g. the 24-bit exponent that's common in X.509 certificates.
 
87
However, being able to relate key IDs to the full
 
88
base64 text form of keys by eye is sufficiently useful that this
 
89
waste of space seems justifiable.
 
90
The choice of nine digits is a compromise between bulk and
 
91
probability of collision.
 
92
.SH SEE ALSO
 
93
RFC 3110,
 
94
\fIRSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS)\fR,
 
95
Eastlake, 2001
 
96
(superseding the older but better-known RFC 2537).
 
97
.SH DIAGNOSTICS
 
98
Fatal errors are:
 
99
key too short to supply enough bits to construct a complete key ID
 
100
(almost certainly indicating a garbage key);
 
101
exponent too long for its length to be representable.
 
102
.SH HISTORY
 
103
Written for the FreeS/WAN project by Henry Spencer.