Paul Wouters

placeholder to suppress warning

IPSEC_KEYBLOBTOID 3 25 March 2002 libreswan Library functions
ipsec keyblobtoid ipsec splitkeytoid generate key IDs from RSA keys

    #include <libreswan.h>

size_t `keyblobtoid` const unsigned char * blob size_t bloblen char * dst size_t dstlen

size_t `splitkeytoid` const unsigned char * e size_t elen const unsigned char * m size_t mlen char * dst size_t dstlen

## DESCRIPTION

Keyblobtoid and `splitkeytoid` generate key IDs from RSA keys, for use in messages and reporting, writing the result to `dst`. A key ID 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.)

Keyblobtoid generates a key ID from a key which is already in the form of an RFC 2537/3110 binary key `blob` (encoded exponent length, exponent, modulus).

Splitkeytoid generates a key ID from a key given in the form of a separate (binary) exponent `e` and modulus `m`.

The `dstlen` parameter of either specifies the size of the `dst` parameter; under no circumstances are more than `dstlen` bytes written to `dst`. A result that will not fit is truncated. Dstlen can be zero, in which case `dst` 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 libreswan.h header file defines a constant KEYID_BUF which is the size of a buffer large enough for worst-case results.

Both functions return `0` for a failure, and otherwise always return the size of buffer that 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 ipsec_rsasigkey 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.

## SEE ALSO

RFC 3110, RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS), Eastlake, 2001 (superseding the older but better-known RFC 2537).

## DIAGNOSTICS

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.

## HISTORY

Written for the FreeS/WAN project by Henry Spencer.