0001 ==================================
0002 Digital Signature Verification API
0003 ==================================
0004
0005 :Author: Dmitry Kasatkin
0006 :Date: 06.10.2011
0007
0008
0009 .. CONTENTS
0010
0011 1. Introduction
0012 2. API
0013 3. User-space utilities
0014
0015
0016 Introduction
0017 ============
0018
0019 Digital signature verification API provides a method to verify digital signature.
0020 Currently digital signatures are used by the IMA/EVM integrity protection subsystem.
0021
0022 Digital signature verification is implemented using cut-down kernel port of
0023 GnuPG multi-precision integers (MPI) library. The kernel port provides
0024 memory allocation errors handling, has been refactored according to kernel
0025 coding style, and checkpatch.pl reported errors and warnings have been fixed.
0026
0027 Public key and signature consist of header and MPIs::
0028
0029 struct pubkey_hdr {
0030 uint8_t version; /* key format version */
0031 time_t timestamp; /* key made, always 0 for now */
0032 uint8_t algo;
0033 uint8_t nmpi;
0034 char mpi[0];
0035 } __packed;
0036
0037 struct signature_hdr {
0038 uint8_t version; /* signature format version */
0039 time_t timestamp; /* signature made */
0040 uint8_t algo;
0041 uint8_t hash;
0042 uint8_t keyid[8];
0043 uint8_t nmpi;
0044 char mpi[0];
0045 } __packed;
0046
0047 keyid equals to SHA1[12-19] over the total key content.
0048 Signature header is used as an input to generate a signature.
0049 Such approach insures that key or signature header could not be changed.
0050 It protects timestamp from been changed and can be used for rollback
0051 protection.
0052
0053 API
0054 ===
0055
0056 API currently includes only 1 function::
0057
0058 digsig_verify() - digital signature verification with public key
0059
0060
0061 /**
0062 * digsig_verify() - digital signature verification with public key
0063 * @keyring: keyring to search key in
0064 * @sig: digital signature
0065 * @sigen: length of the signature
0066 * @data: data
0067 * @datalen: length of the data
0068 * @return: 0 on success, -EINVAL otherwise
0069 *
0070 * Verifies data integrity against digital signature.
0071 * Currently only RSA is supported.
0072 * Normally hash of the content is used as a data for this function.
0073 *
0074 */
0075 int digsig_verify(struct key *keyring, const char *sig, int siglen,
0076 const char *data, int datalen);
0077
0078 User-space utilities
0079 ====================
0080
0081 The signing and key management utilities evm-utils provide functionality
0082 to generate signatures, to load keys into the kernel keyring.
0083 Keys can be in PEM or converted to the kernel format.
0084 When the key is added to the kernel keyring, the keyid defines the name
0085 of the key: 5D2B05FC633EE3E8 in the example bellow.
0086
0087 Here is example output of the keyctl utility::
0088
0089 $ keyctl show
0090 Session Keyring
0091 -3 --alswrv 0 0 keyring: _ses
0092 603976250 --alswrv 0 -1 \_ keyring: _uid.0
0093 817777377 --alswrv 0 0 \_ user: kmk
0094 891974900 --alswrv 0 0 \_ encrypted: evm-key
0095 170323636 --alswrv 0 0 \_ keyring: _module
0096 548221616 --alswrv 0 0 \_ keyring: _ima
0097 128198054 --alswrv 0 0 \_ keyring: _evm
0098
0099 $ keyctl list 128198054
0100 1 key in keyring:
0101 620789745: --alswrv 0 0 user: 5D2B05FC633EE3E8
