| 1 | ==================================
|
| 2 | Digital Signature Verification API
|
| 3 | ==================================
|
| 4 |
|
| 5 | :Author: Dmitry Kasatkin
|
| 6 | :Date: 06.10.2011
|
| 7 |
|
| 8 |
|
| 9 | |
| 10 |
|
| 11 | 1. Introduction
|
| 12 | 2. API
|
| 13 | 3. User-space utilities
|
| 14 |
|
| 15 |
|
| 16 | Introduction
|
| 17 | ============
|
| 18 |
|
| 19 | Digital signature verification API provides a method to verify digital signature.
|
| 20 | Currently digital signatures are used by the IMA/EVM integrity protection subsystem.
|
| 21 |
|
| 22 | Digital signature verification is implemented using cut-down kernel port of
|
| 23 | GnuPG multi-precision integers (MPI) library. The kernel port provides
|
| 24 | memory allocation errors handling, has been refactored according to kernel
|
| 25 | coding style, and checkpatch.pl reported errors and warnings have been fixed.
|
| 26 |
|
| 27 | Public 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 |
|
| 47 | keyid equals to SHA1[12-19] over the total key content.
|
| 48 | Signature header is used as an input to generate a signature.
|
| 49 | Such approach insures that key or signature header could not be changed.
|
| 50 | It protects timestamp from been changed and can be used for rollback
|
| 51 | protection.
|
| 52 |
|
| 53 | API
|
| 54 | ===
|
| 55 |
|
| 56 | API 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 |
|
| 78 | User-space utilities
|
| 79 | ====================
|
| 80 |
|
| 81 | The signing and key management utilities evm-utils provide functionality
|
| 82 | to generate signatures, to load keys into the kernel keyring.
|
| 83 | Keys can be in PEM or converted to the kernel format.
|
| 84 | When the key is added to the kernel keyring, the keyid defines the name
|
| 85 | of the key: 5D2B05FC633EE3E8 in the example below.
|
| 86 |
|
| 87 | Here 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
|