[thirdparty/strongswan.git] / doc / manpage.d / ipsec_splitkeytoid.3.html

Content-type: text/html

<HTML><HEAD><TITLE>Manpage of IPSEC_KEYBLOBTOID</TITLE>
</HEAD><BODY>
<H1>IPSEC_KEYBLOBTOID</H1>
Section: C Library Functions (3)<BR>Updated: 25 March 2002<BR><A HREF="#index">Index</A>
<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>


<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>

ipsec keyblobtoid, splitkeytoid - generate key IDs from RSA keys
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>

<P>
<B>size_t keyblobtoid(const unsigned char *blob,</B>

<BR>
&nbsp;
<B>size_t bloblen, char *dst, size_t dstlen);</B>

<BR>

<B>size_t splitkeytoid(const unsigned char *e, size_t elen,</B>

<BR>
&nbsp;
<B>const unsigned char *m, size_t mlen, char *dst,</B>

<BR>
&nbsp;
<B>size_t dstlen);</B>

<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>

<I>Keyblobtoid</I>

and
<I>splitkeytoid</I>

generate
key IDs
from RSA keys,
for use in messages and reporting,
writing the result to
<I>dst</I>.

A
<I>key ID</I>

is a short ASCII string identifying a key;
currently it is just the first nine characters of the base64
encoding of the RFC 2537/3110 ``byte blob'' representation of the key.
(Beware that no finite key ID can be collision-proof:
there is always some small chance of two random keys having the
same ID.)
<P>

<I>Keyblobtoid</I>

generates a key ID from a key which is already in the form of an
RFC 2537/3110 binary key
<I>blob</I>

(encoded exponent length, exponent, modulus).
<P>

<I>Splitkeytoid</I>

generates a key ID from a key given in the form of a separate
(binary) exponent
<I>e</I>

and modulus
<I>m</I>.

<P>

The
<I>dstlen</I>

parameter of either
specifies the size of the
<I>dst</I>

parameter;
under no circumstances are more than
<I>dstlen</I>

bytes written to
<I>dst</I>.

A result which will not fit is truncated.
<I>Dstlen</I>

can be zero, in which case
<I>dst</I>

need not be valid and no result is written,
but the return value is unaffected;
in all other cases, the (possibly truncated) result is NUL-terminated.
The
<I>freeswan.h</I>

header file defines a constant
<B>KEYID_BUF</B>

which is the size of a buffer large enough for worst-case results.
<P>

Both functions return
<B>0</B>

for a failure, and otherwise
always return the size of buffer which would 
be needed to
accommodate the full conversion result, including terminating NUL;
it is the caller's responsibility to check this against the size of
the provided buffer to determine whether truncation has occurred.

With keys generated by
<I><A HREF="ipsec_rsasigkey.3.html">ipsec_rsasigkey</A></I>(3),

the first two base64 digits are always the same,
and the third carries only about one bit of information.
It's worse with keys using longer fixed exponents,
e.g. the 24-bit exponent that's common in X.509 certificates.
However, being able to relate key IDs to the full
base64 text form of keys by eye is sufficiently useful that this
waste of space seems justifiable.
The choice of nine digits is a compromise between bulk and
probability of collision.
<A NAME="lbAE">&nbsp;</A>
<H2>SEE ALSO</H2>

RFC 3110,
<I>RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS)</I>,
Eastlake, 2001
(superseding the older but better-known RFC 2537).
<A NAME="lbAF">&nbsp;</A>
<H2>DIAGNOSTICS</H2>

Fatal errors are:
key too short to supply enough bits to construct a complete key ID
(almost certainly indicating a garbage key);
exponent too long for its length to be representable.
<A NAME="lbAG">&nbsp;</A>
<H2>HISTORY</H2>

Written for the FreeS/WAN project by Henry Spencer.
<P>

<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">SEE ALSO</A><DD>
<DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
<DT><A HREF="#lbAG">HISTORY</A><DD>
</DL>
<HR>
This document was created by
<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 21:40:18 GMT, November 11, 2003
</BODY>
</HTML>
Commit	Line	Data
997358a6 MW	1	Content-type: text/html
	2
	3	<HTML><HEAD><TITLE>Manpage of IPSEC_KEYBLOBTOID</TITLE>
	4	</HEAD><BODY>
	5	<H1>IPSEC_KEYBLOBTOID</H1>
	6	Section: C Library Functions (3)<BR>Updated: 25 March 2002<BR><A HREF="#index">Index</A>
	7	<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
	8
	9
	10	<A NAME="lbAB"> </A>
	11	<H2>NAME</H2>
	12
	13	ipsec keyblobtoid, splitkeytoid - generate key IDs from RSA keys
	14	<A NAME="lbAC"> </A>
	15	<H2>SYNOPSIS</H2>
	16
	17	<B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B>
	18
	19	<P>
	20	<B>size_t keyblobtoid(const unsigned char *blob,</B>
	21
	22	<BR>
	23
	24	<B>size_t bloblen, char *dst, size_t dstlen);</B>
	25
	26	<BR>
	27
	28	<B>size_t splitkeytoid(const unsigned char *e, size_t elen,</B>
	29
	30	<BR>
	31
	32	<B>const unsigned char m, size_t mlen, char dst,</B>
	33
	34	<BR>
	35
	36	<B>size_t dstlen);</B>
	37
	38	<A NAME="lbAD"> </A>
	39	<H2>DESCRIPTION</H2>
	40
	41	<I>Keyblobtoid</I>
	42
	43	and
	44	<I>splitkeytoid</I>
	45
	46	generate
	47	key IDs
	48	from RSA keys,
	49	for use in messages and reporting,
	50	writing the result to
	51	<I>dst</I>.
	52
	53	A
	54	<I>key ID</I>
	55
	56	is a short ASCII string identifying a key;
	57	currently it is just the first nine characters of the base64
	58	encoding of the RFC 2537/3110 ``byte blob'' representation of the key.
	59	(Beware that no finite key ID can be collision-proof:
	60	there is always some small chance of two random keys having the
	61	same ID.)
	62	<P>
	63
	64	<I>Keyblobtoid</I>
65
66	generates a key ID from a key which is already in the form of an
67	RFC 2537/3110 binary key
68	<I>blob</I>
69
70	(encoded exponent length, exponent, modulus).
71	<P>
72
73	<I>Splitkeytoid</I>
74
75	generates a key ID from a key given in the form of a separate
76	(binary) exponent
77	<I>e</I>
78
79	and modulus
80	<I>m</I>.
81
82	<P>
83
84	The
85	<I>dstlen</I>
86
87	parameter of either
88	specifies the size of the
89	<I>dst</I>
90
91	parameter;
92	under no circumstances are more than
93	<I>dstlen</I>
94
95	bytes written to
96	<I>dst</I>.
97
98	A result which will not fit is truncated.
99	<I>Dstlen</I>
100
101	can be zero, in which case
102	<I>dst</I>
103
104	need not be valid and no result is written,
105	but the return value is unaffected;
106	in all other cases, the (possibly truncated) result is NUL-terminated.
107	The
108	<I>freeswan.h</I>
109
110	header file defines a constant
111	<B>KEYID_BUF</B>
112
113	which is the size of a buffer large enough for worst-case results.
114	<P>
115
116	Both functions return
117	<B>0</B>
118
119	for a failure, and otherwise
120	always return the size of buffer which would
121	be needed to
122	accommodate the full conversion result, including terminating NUL;
123	it is the caller's responsibility to check this against the size of
124	the provided buffer to determine whether truncation has occurred.
125
126	With keys generated by
127	<I><A HREF="ipsec_rsasigkey.3.html">ipsec_rsasigkey</A></I>(3),
128
129	the first two base64 digits are always the same,
130	and the third carries only about one bit of information.
131	It's worse with keys using longer fixed exponents,
132	e.g. the 24-bit exponent that's common in X.509 certificates.
133	However, being able to relate key IDs to the full
134	base64 text form of keys by eye is sufficiently useful that this
135	waste of space seems justifiable.
136	The choice of nine digits is a compromise between bulk and
137	probability of collision.
138	<A NAME="lbAE"> </A>
139	<H2>SEE ALSO</H2>
140
141	RFC 3110,
142	<I>RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS)</I>,
143	Eastlake, 2001
144	(superseding the older but better-known RFC 2537).
145	<A NAME="lbAF"> </A>
146	<H2>DIAGNOSTICS</H2>
147
148	Fatal errors are:
149	key too short to supply enough bits to construct a complete key ID
150	(almost certainly indicating a garbage key);
151	exponent too long for its length to be representable.
152	<A NAME="lbAG"> </A>
153	<H2>HISTORY</H2>
154
155	Written for the FreeS/WAN project by Henry Spencer.
156	<P>
157
158	<HR>
159	<A NAME="index"> </A><H2>Index</H2>
160	<DL>
161	<DT><A HREF="#lbAB">NAME</A><DD>
162	<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
163	<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
164	<DT><A HREF="#lbAE">SEE ALSO</A><DD>
165	<DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
166	<DT><A HREF="#lbAG">HISTORY</A><DD>
167	</DL>
168	<HR>
169	This document was created by
170	<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
171	using the manual pages.<BR>
172	Time: 21:40:18 GMT, November 11, 2003
173	</BODY>
174	</HTML>