doc/manpage.d/ipsec_keyblobtoid.3.html

   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">&nbsp;</A>
  11 <H2>NAME</H2>
  12
  13 ipsec keyblobtoid, splitkeytoid - generate key IDs from RSA keys
  14 <A NAME="lbAC">&nbsp;</A>
  15 <H2>SYNOPSIS</H2>
  16
  17 <B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
  18
  19 <P>
  20 <B>size_t keyblobtoid(const unsigned char *blob,</B>
  21
  22 <BR>
  23 &nbsp;
  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 &nbsp;
  32 <B>const unsigned char *m, size_t mlen, char *dst,</B>
  33
  34 <BR>
  35 &nbsp;
  36 <B>size_t dstlen);</B>
  37
  38 <A NAME="lbAD">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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>