From 051dbb918c7fb7da8e64a2cd0d804ba73399709f Mon Sep 17 00:00:00 2001 From: Dmitry Kasatkin Date: Fri, 14 Oct 2011 15:25:16 +0300 Subject: crypto: digital signature verification support This patch implements RSA digital signature verification using GnuPG library. The format of the signature and the public key is defined by their respective headers. The signature header contains version information, algorithm, and keyid, which was used to generate the signature. The key header contains version and algorythim type. The payload of the signature and the key are multi-precision integers. The signing and key management utilities evm-utils provide functionality to generate signatures and load keys into the kernel keyring. When the key is added to the kernel keyring, the keyid defines the name of the key. Signed-off-by: Dmitry Kasatkin Acked-by: Mimi Zohar --- Documentation/digsig.txt | 96 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 Documentation/digsig.txt (limited to 'Documentation') diff --git a/Documentation/digsig.txt b/Documentation/digsig.txt new file mode 100644 index 000000000000..3f682889068b --- /dev/null +++ b/Documentation/digsig.txt @@ -0,0 +1,96 @@ +Digital Signature Verification API + +CONTENTS + +1. Introduction +2. API +3. User-space utilities + + +1. Introduction + +Digital signature verification API provides a method to verify digital signature. +Currently digital signatures are used by the IMA/EVM integrity protection subsystem. + +Digital signature verification is implemented using cut-down kernel port of +GnuPG multi-precision integers (MPI) library. The kernel port provides +memory allocation errors handling, has been refactored according to kernel +coding style, and checkpatch.pl reported errors and warnings have been fixed. + +Public key and signature consist of header and MPIs. + +struct pubkey_hdr { + uint8_t version; /* key format version */ + time_t timestamp; /* key made, always 0 for now */ + uint8_t algo; + uint8_t nmpi; + char mpi[0]; +} __packed; + +struct signature_hdr { + uint8_t version; /* signature format version */ + time_t timestamp; /* signature made */ + uint8_t algo; + uint8_t hash; + uint8_t keyid[8]; + uint8_t nmpi; + char mpi[0]; +} __packed; + +keyid equals to SHA1[12-19] over the total key content. +Signature header is used as an input to generate a signature. +Such approach insures that key or signature header could not be changed. +It protects timestamp from been changed and can be used for rollback +protection. + +2. API + +API currently includes only 1 function: + + digsig_verify() - digital signature verification with public key + + +/** + * digsig_verify() - digital signature verification with public key + * @keyring: keyring to search key in + * @sig: digital signature + * @sigen: length of the signature + * @data: data + * @datalen: length of the data + * @return: 0 on success, -EINVAL otherwise + * + * Verifies data integrity against digital signature. + * Currently only RSA is supported. + * Normally hash of the content is used as a data for this function. + * + */ +int digsig_verify(struct key *keyring, const char *sig, int siglen, + const char *data, int datalen); + +3. User-space utilities + +The signing and key management utilities evm-utils provide functionality +to generate signatures, to load keys into the kernel keyring. +Keys can be in PEM or converted to the kernel format. +When the key is added to the kernel keyring, the keyid defines the name +of the key: 5D2B05FC633EE3E8 in the example bellow. + +Here is example output of the keyctl utility. + +$ keyctl show +Session Keyring + -3 --alswrv 0 0 keyring: _ses +603976250 --alswrv 0 -1 \_ keyring: _uid.0 +817777377 --alswrv 0 0 \_ user: kmk +891974900 --alswrv 0 0 \_ encrypted: evm-key +170323636 --alswrv 0 0 \_ keyring: _module +548221616 --alswrv 0 0 \_ keyring: _ima +128198054 --alswrv 0 0 \_ keyring: _evm + +$ keyctl list 128198054 +1 key in keyring: +620789745: --alswrv 0 0 user: 5D2B05FC633EE3E8 + + +Dmitry Kasatkin +06.10.2011 -- cgit v1.2.3-59-g8ed1b From e163bc8e4a0cd1cdffadb58253f7651201722d56 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Tue, 1 Nov 2011 17:20:01 -0700 Subject: Documentation: clarify the purpose of LSMs Clarify the purpose of the LSM interface with some brief examples and pointers to additional documentation. Signed-off-by: Kees Cook Signed-off-by: James Morris --- Documentation/security/00-INDEX | 2 ++ Documentation/security/LSM.txt | 34 ++++++++++++++++++++++++++++++++++ Documentation/security/credentials.txt | 6 +++--- 3 files changed, 39 insertions(+), 3 deletions(-) create mode 100644 Documentation/security/LSM.txt (limited to 'Documentation') diff --git a/Documentation/security/00-INDEX b/Documentation/security/00-INDEX index 19bc49439cac..99b85d39751c 100644 --- a/Documentation/security/00-INDEX +++ b/Documentation/security/00-INDEX @@ -1,5 +1,7 @@ 00-INDEX - this file. +LSM.txt + - description of the Linux Security Module framework. SELinux.txt - how to get started with the SELinux security enhancement. Smack.txt diff --git a/Documentation/security/LSM.txt b/Documentation/security/LSM.txt new file mode 100644 index 000000000000..c335a763a2ed --- /dev/null +++ b/Documentation/security/LSM.txt @@ -0,0 +1,34 @@ +Linux Security Module framework +------------------------------- + +The Linux Security Module (LSM) framework provides a mechanism for +various security checks to be hooked by new kernel extensions. The name +"module" is a bit of a misnomer since these extensions are not actually +loadable kernel modules. Instead, they are selectable at build-time via +CONFIG_DEFAULT_SECURITY and can be overridden at boot-time via the +"security=..." kernel command line argument, in the case where multiple +LSMs were built into a given kernel. + +The primary users of the LSM interface are Mandatory Access Control +(MAC) extensions which provide a comprehensive security policy. Examples +include SELinux, Smack, Tomoyo, and AppArmor. In addition to the larger +MAC extensions, other extensions can be built using the LSM to provide +specific changes to system operation when these tweaks are not available +in the core functionality of Linux itself. + +Without a specific LSM built into the kernel, the default LSM will be the +Linux capabilities system. Most LSMs choose to extend the capabilities +system, building their checks on top of the defined capability hooks. +For more details on capabilities, see capabilities(7) in the Linux +man-pages project. + +Based on http://kerneltrap.org/Linux/Documenting_Security_Module_Intent, +a new LSM is accepted into the kernel when its intent (a description of +what it tries to protect against and in what cases one would expect to +use it) has been appropriately documented in Documentation/security/. +This allows an LSM's code to be easily compared to its goals, and so +that end users and distros can make a more informed decision about which +LSMs suit their requirements. + +For extensive documentation on the available LSM hook interfaces, please +see include/linux/security.h. diff --git a/Documentation/security/credentials.txt b/Documentation/security/credentials.txt index fc0366cbd7ce..86257052e31a 100644 --- a/Documentation/security/credentials.txt +++ b/Documentation/security/credentials.txt @@ -221,10 +221,10 @@ The Linux kernel supports the following types of credentials: (5) LSM The Linux Security Module allows extra controls to be placed over the - operations that a task may do. Currently Linux supports two main - alternate LSM options: SELinux and Smack. + operations that a task may do. Currently Linux supports several LSM + options. - Both work by labelling the objects in a system and then applying sets of + Some work by labelling the objects in a system and then applying sets of rules (policies) that say what operations a task with one label may do to an object with another label. -- cgit v1.2.3-59-g8ed1b