diff options
Diffstat (limited to 'Documentation/crypto')
| -rw-r--r-- | Documentation/crypto/api-samples.rst | 38 | ||||
| -rw-r--r-- | Documentation/crypto/asymmetric-keys.txt | 67 | ||||
| -rw-r--r-- | Documentation/crypto/conf.py | 10 | ||||
| -rw-r--r-- | Documentation/crypto/userspace-if.rst | 2 |
4 files changed, 97 insertions, 20 deletions
diff --git a/Documentation/crypto/api-samples.rst b/Documentation/crypto/api-samples.rst index d021fd96a76d..2531948db89f 100644 --- a/Documentation/crypto/api-samples.rst +++ b/Documentation/crypto/api-samples.rst @@ -155,9 +155,9 @@ Code Example For Use of Operational State Memory With SHASH char ctx[]; }; - static struct sdesc init_sdesc(struct crypto_shash *alg) + static struct sdesc *init_sdesc(struct crypto_shash *alg) { - struct sdesc sdesc; + struct sdesc *sdesc; int size; size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); @@ -169,15 +169,16 @@ Code Example For Use of Operational State Memory With SHASH return sdesc; } - static int calc_hash(struct crypto_shashalg, - const unsigned chardata, unsigned int datalen, - unsigned chardigest) { - struct sdesc sdesc; + static int calc_hash(struct crypto_shash *alg, + const unsigned char *data, unsigned int datalen, + unsigned char *digest) + { + struct sdesc *sdesc; int ret; sdesc = init_sdesc(alg); if (IS_ERR(sdesc)) { - pr_info("trusted_key: can't alloc %s\n", hash_alg); + pr_info("can't alloc sdesc\n"); return PTR_ERR(sdesc); } @@ -186,6 +187,23 @@ Code Example For Use of Operational State Memory With SHASH return ret; } + static int test_hash(const unsigned char *data, unsigned int datalen, + unsigned char *digest) + { + struct crypto_shash *alg; + char *hash_alg_name = "sha1-padlock-nano"; + int ret; + + alg = crypto_alloc_shash(hash_alg_name, CRYPTO_ALG_TYPE_SHASH, 0); + if (IS_ERR(alg)) { + pr_info("can't alloc alg %s\n", hash_alg_name); + return PTR_ERR(alg); + } + ret = calc_hash(alg, data, datalen, digest); + crypto_free_shash(alg); + return ret; + } + Code Example For Random Number Generator Usage ---------------------------------------------- @@ -195,8 +213,8 @@ Code Example For Random Number Generator Usage static int get_random_numbers(u8 *buf, unsigned int len) { - struct crypto_rngrng = NULL; - chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ + struct crypto_rng *rng = NULL; + char *drbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ int ret; if (!buf || !len) { @@ -207,7 +225,7 @@ Code Example For Random Number Generator Usage rng = crypto_alloc_rng(drbg, 0, 0); if (IS_ERR(rng)) { pr_debug("could not allocate RNG handle for %s\n", drbg); - return -PTR_ERR(rng); + return PTR_ERR(rng); } ret = crypto_rng_get_bytes(rng, buf, len); diff --git a/Documentation/crypto/asymmetric-keys.txt b/Documentation/crypto/asymmetric-keys.txt index 5ad6480e3fb9..5969bf42562a 100644 --- a/Documentation/crypto/asymmetric-keys.txt +++ b/Documentation/crypto/asymmetric-keys.txt @@ -10,6 +10,7 @@ Contents: - Signature verification. - Asymmetric key subtypes. - Instantiation data parsers. + - Keyring link restrictions. ======== @@ -265,7 +266,7 @@ mandatory: The caller passes a pointer to the following struct with all of the fields cleared, except for data, datalen and quotalen [see - Documentation/security/keys.txt]. + Documentation/security/keys/core.rst]. struct key_preparsed_payload { char *description; @@ -318,7 +319,8 @@ KEYRING LINK RESTRICTIONS ========================= Keyrings created from userspace using add_key can be configured to check the -signature of the key being linked. +signature of the key being linked. Keys without a valid signature are not +allowed to link. Several restriction methods are available: @@ -327,9 +329,10 @@ Several restriction methods are available: - Option string used with KEYCTL_RESTRICT_KEYRING: - "builtin_trusted" - The kernel builtin trusted keyring will be searched for the signing - key. The ca_keys kernel parameter also affects which keys are used for - signature verification. + The kernel builtin trusted keyring will be searched for the signing key. + If the builtin trusted keyring is not configured, all links will be + rejected. The ca_keys kernel parameter also affects which keys are used + for signature verification. (2) Restrict using the kernel builtin and secondary trusted keyrings @@ -337,8 +340,10 @@ Several restriction methods are available: - "builtin_and_secondary_trusted" The kernel builtin and secondary trusted keyrings will be searched for the - signing key. The ca_keys kernel parameter also affects which keys are used - for signature verification. + signing key. If the secondary trusted keyring is not configured, this + restriction will behave like the "builtin_trusted" option. The ca_keys + kernel parameter also affects which keys are used for signature + verification. (3) Restrict using a separate key or keyring @@ -346,7 +351,7 @@ Several restriction methods are available: - "key_or_keyring:<key or keyring serial number>[:chain]" Whenever a key link is requested, the link will only succeed if the key - being linked is signed by one of the designated keys. This key may be + being linked is signed by one of the designated keys. This key may be specified directly by providing a serial number for one asymmetric key, or a group of keys may be searched for the signing key by providing the serial number for a keyring. @@ -354,7 +359,51 @@ Several restriction methods are available: When the "chain" option is provided at the end of the string, the keys within the destination keyring will also be searched for signing keys. This allows for verification of certificate chains by adding each - cert in order (starting closest to the root) to one keyring. + certificate in order (starting closest to the root) to a keyring. For + instance, one keyring can be populated with links to a set of root + certificates, with a separate, restricted keyring set up for each + certificate chain to be validated: + + # Create and populate a keyring for root certificates + root_id=`keyctl add keyring root-certs "" @s` + keyctl padd asymmetric "" $root_id < root1.cert + keyctl padd asymmetric "" $root_id < root2.cert + + # Create and restrict a keyring for the certificate chain + chain_id=`keyctl add keyring chain "" @s` + keyctl restrict_keyring $chain_id asymmetric key_or_keyring:$root_id:chain + + # Attempt to add each certificate in the chain, starting with the + # certificate closest to the root. + keyctl padd asymmetric "" $chain_id < intermediateA.cert + keyctl padd asymmetric "" $chain_id < intermediateB.cert + keyctl padd asymmetric "" $chain_id < end-entity.cert + + If the final end-entity certificate is successfully added to the "chain" + keyring, we can be certain that it has a valid signing chain going back to + one of the root certificates. + + A single keyring can be used to verify a chain of signatures by + restricting the keyring after linking the root certificate: + + # Create a keyring for the certificate chain and add the root + chain2_id=`keyctl add keyring chain2 "" @s` + keyctl padd asymmetric "" $chain2_id < root1.cert + + # Restrict the keyring that already has root1.cert linked. The cert + # will remain linked by the keyring. + keyctl restrict_keyring $chain2_id asymmetric key_or_keyring:0:chain + + # Attempt to add each certificate in the chain, starting with the + # certificate closest to the root. + keyctl padd asymmetric "" $chain2_id < intermediateA.cert + keyctl padd asymmetric "" $chain2_id < intermediateB.cert + keyctl padd asymmetric "" $chain2_id < end-entity.cert + + If the final end-entity certificate is successfully added to the "chain2" + keyring, we can be certain that there is a valid signing chain going back + to the root certificate that was added before the keyring was restricted. + In all of these cases, if the signing key is found the signature of the key to be linked will be verified using the signing key. The requested key is added diff --git a/Documentation/crypto/conf.py b/Documentation/crypto/conf.py new file mode 100644 index 000000000000..4335d251ddf3 --- /dev/null +++ b/Documentation/crypto/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel Crypto API' + +tags.add("subproject") + +latex_documents = [ + ('index', 'crypto-api.tex', 'Linux Kernel Crypto API manual', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/crypto/userspace-if.rst b/Documentation/crypto/userspace-if.rst index de5a72e32bc9..ff86befa61e0 100644 --- a/Documentation/crypto/userspace-if.rst +++ b/Documentation/crypto/userspace-if.rst @@ -327,7 +327,7 @@ boundary. Non-aligned data can be used as well, but may require more operations of the kernel which would defeat the speed gains obtained from the zero-copy interface. -The system-interent limit for the size of one zero-copy operation is 16 +The system-inherent limit for the size of one zero-copy operation is 16 pages. If more data is to be sent to AF_ALG, user space must slice the input into segments with a maximum size of 16 pages. |