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