Lines Matching refs:the
19 The "asymmetric" key type is designed to be a container for the keys used in
20 public-key cryptography, without imposing any particular restrictions on the
21 form or mechanism of the cryptography or form of the key.
24 associated with the key and provides operations to describe and destroy it.
25 However, no requirement is made that the key data actually be stored in the
30 a TPM) that might be used to both retain the relevant key and perform
31 operations using that key. In such a case, the asymmetric key would then
32 merely be an interface to the TPM driver.
34 Also provided is the concept of a data parser. Data parsers are responsible
35 for extracting information from the blobs of data passed to the instantiation
36 function. The first data parser that recognises the blob gets to set the
37 subtype of the key and define the operations that can be done on that key.
39 A data parser may interpret the data blob as containing the bits representing a
40 key, or it may interpret it as a reference to a key held somewhere else in the
48 If a key is added with an empty name, the instantiation data parsers are given
49 the opportunity to pre-parse a key and to determine the description the key
50 should be given from the content of the key.
52 This can then be used to refer to the key, either by complete match or by
56 comparisons than just the straightforward comparison of the description with
57 the criterion string:
59 (1) If the criterion string is of the form "id:<hexdigits>" then the match
60 function will examine a key's fingerprint to see if the hex digits given
61 after the "id:" match the tail. For instance:
69 (2) If the criterion string is of the form "<subtype>:<hexdigits>" then the
70 match will match the ID as in (1), but with the added restriction that
71 only keys of the specified subtype (e.g. tpm) will be matched. For
76 Looking in /proc/keys, the last 8 hex digits of the key fingerprint are
77 displayed, along with the subtype:
86 For general access to asymmetric keys from within the kernel, the following
105 Note that the key type representation types are required because key
107 instance, PGP generates key identifiers by hashing the key data plus some
114 Other operations are possible (such as encryption) with the same key data
123 an asymmetric key to provide or to provide access to the public key.
128 The caller must have already obtained the key from some source and can then use
129 it to check the signature. The caller must have parsed the signature and
130 transferred the relevant bits to the structure pointed to by sig.
143 The algorithm used must be noted in sig->pkey_hash_algo, and all the MPIs that
144 make up the actual signature must be stored in sig->mpi[] and the count of MPIs
147 In addition, the data must have been digested by the caller and the resulting
148 hash must be pointed to by sig->digest and the size of the hash be placed in
151 The function will return 0 upon success or -EKEYREJECTED if the signature
155 or public-key/hash algorithm combination is specified or the key doesn't
156 support the operation; -EBADMSG or -ERANGE if some of the parameters have weird
158 if the key argument is the wrong type or is incompletely set up.
165 Asymmetric keys have a subtype that defines the set of operations that can be
166 performed on that key and that determines what data is attached as the key
167 payload. The payload format is entirely at the whim of the subtype.
169 The subtype is selected by the key data parser and the parser must initialise
170 the data required for it. The asymmetric key retains a reference on the
177 and looks like the following:
191 The owner and name fields should be set to the owning module and the name of
192 the subtype. Currently, the name is only used for print statements.
194 There are a number of operations defined by the subtype:
198 Mandatory. This allows the subtype to display something in /proc/keys
199 against the key. For instance the name of the public key algorithm type
200 could be displayed. The key type will display the tail of the key
205 Mandatory. This should free the memory associated with the key. The
206 asymmetric key will look after freeing the fingerprint and releasing the
207 reference on the subtype module.
211 Optional. These are the entry points for the key usage operations.
212 Currently there is only the one defined. If not set, the caller will be
222 blob of data that holds the key data. It would have to parse it and error
223 check it each time it wanted to use it. Further, the contents of the blob may
225 dates) and may contain useful data about the key (identifiers, capabilities).
227 Also, the blob may represent a pointer to some hardware containing the key
228 rather than the key itself.
237 During key instantiation each parser in the list is tried until one doesn't
244 and looks like the following:
253 The owner and name fields should be set to the owning module and the name of
254 the parser.
256 There is currently only a single operation defined by the parser, and it is
261 This is called to preparse the key from the key creation and update paths.
262 In particular, it is called during the key creation _before_ a key is
263 allocated, and as such, is permitted to provide the key's description in
264 the case that the caller declines to do so.
266 The caller passes a pointer to the following struct with all of the fields
280 all, and shouldn't change any of the other values _unless_ they are
281 recognise the blob format and will not return -EBADMSG to indicate it is
284 If the parser is happy with the blob, it should propose a description for
285 the key and attach it to ->description, ->payload[asym_subtype] should be
286 set to point to the subtype to be used, ->payload[asym_crypto] should be
287 set to point to the initialised data for that subtype,
292 When clearing up, the data attached to ->payload[asym_key_ids] and
293 ->description will be kfree()'d and the data attached to
294 ->payload[asm_crypto] will be passed to the subtype's ->destroy() method
295 to be disposed of. A module reference for the subtype pointed to by
299 If the data format is not recognised, -EBADMSG should be returned. If it
300 is recognised, but the key cannot for some reason be set up, some other
305 hex version of the key's fingerprint.
312 Parsers may not have the same name. The names are otherwise only used for