LXR linux/Documentation/digsig.txt

   1Digital Signature Verification API
   2
   3CONTENTS
   4
   51. Introduction
   62. API
   73. User-space utilities
   8
   9
  101. Introduction
  11
  12Digital signature verification API provides a method to verify digital signature.
  13Currently digital signatures are used by the IMA/EVM integrity protection subsystem.
  14
  15Digital signature verification is implemented using cut-down kernel port of
  16GnuPG multi-precision integers (MPI) library. The kernel port provides
  17memory allocation errors handling, has been refactored according to kernel
  18coding style, and checkpatch.pl reported errors and warnings have been fixed.
  19
  20Public key and signature consist of header and MPIs.
  21
  22struct pubkey_hdr {
  23        uint8_t         version;        /* key format version */
  24        time_t          timestamp;      /* key made, always 0 for now */
  25        uint8_t         algo;
  26        uint8_t         nmpi;
  27        char            mpi[0];
  28} __packed;
  29
  30struct signature_hdr {
  31        uint8_t         version;        /* signature format version */
  32        time_t          timestamp;      /* signature made */
  33        uint8_t         algo;
  34        uint8_t         hash;
  35        uint8_t         keyid[8];
  36        uint8_t         nmpi;
  37        char            mpi[0];
  38} __packed;
  39
  40keyid equals to SHA1[12-19] over the total key content.
  41Signature header is used as an input to generate a signature.
  42Such approach insures that key or signature header could not be changed.
  43It protects timestamp from been changed and can be used for rollback
  44protection.
  45
  462. API
  47
  48API currently includes only 1 function:
  49
  50        digsig_verify() - digital signature verification with public key
  51
  52
  53/**
  54 * digsig_verify() - digital signature verification with public key
  55 * @keyring:    keyring to search key in
  56 * @sig:        digital signature
  57 * @sigen:      length of the signature
  58 * @data:       data
  59 * @datalen:    length of the data
  60 * @return:     0 on success, -EINVAL otherwise
  61 *
  62 * Verifies data integrity against digital signature.
  63 * Currently only RSA is supported.
  64 * Normally hash of the content is used as a data for this function.
  65 *
  66 */
  67int digsig_verify(struct key *keyring, const char *sig, int siglen,
  68                                                const char *data, int datalen);
  69
  703. User-space utilities
  71
  72The signing and key management utilities evm-utils provide functionality
  73to generate signatures, to load keys into the kernel keyring.
  74Keys can be in PEM or converted to the kernel format.
  75When the key is added to the kernel keyring, the keyid defines the name
  76of the key: 5D2B05FC633EE3E8 in the example bellow.
  77
  78Here is example output of the keyctl utility.
  79
  80$ keyctl show
  81Session Keyring
  82       -3 --alswrv      0     0  keyring: _ses
  83603976250 --alswrv      0    -1   \_ keyring: _uid.0
  84817777377 --alswrv      0     0       \_ user: kmk
  85891974900 --alswrv      0     0       \_ encrypted: evm-key
  86170323636 --alswrv      0     0       \_ keyring: _module
  87548221616 --alswrv      0     0       \_ keyring: _ima
  88128198054 --alswrv      0     0       \_ keyring: _evm
  89
  90$ keyctl list 128198054
  911 key in keyring:
  92620789745: --alswrv     0     0 user: 5D2B05FC633EE3E8
  93
  94
  95Dmitry Kasatkin
  9606.10.2011
  97