digsig.rst 3.0 KB

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