~hc/RK356X_SDK_RELEASE.git

..	..	@@ -433,6 +433,10 @@
433	433	/sbin/request-key will be invoked in an attempt to obtain a key. The
434	434	callout_info string will be passed as an argument to the program.
435	435
	436	+ To link a key into the destination keyring the key must grant link
	437	+ permission on the key to the caller and the keyring must grant write
	438	+ permission.
	439	+
436	440	See also Documentation/security/keys/request-key.rst.
437	441
438	442
..	..	@@ -575,6 +579,27 @@
575	579	Any links within the keyring to keys that match the new key in terms of
576	580	type and description will be discarded from the keyring as the new one is
577	581	added.
	582	+
	583	+
	584	+ * Move a key from one keyring to another::
	585	+
	586	+ long keyctl(KEYCTL_MOVE,
	587	+ key_serial_t id,
	588	+ key_serial_t from_ring_id,
	589	+ key_serial_t to_ring_id,
	590	+ unsigned int flags);
	591	+
	592	+ Move the key specified by "id" from the keyring specified by
	593	+ "from_ring_id" to the keyring specified by "to_ring_id". If the two
	594	+ keyrings are the same, nothing is done.
	595	+
	596	+ "flags" can have KEYCTL_MOVE_EXCL set in it to cause the operation to fail
	597	+ with EEXIST if a matching key exists in the destination keyring, otherwise
	598	+ such a key will be replaced.
	599	+
	600	+ A process must have link permission on the key for this function to be
	601	+ successful and write permission on both keyrings. Any errors that can
	602	+ occur from KEYCTL_LINK also apply on the destination keyring here.
578	603
579	604
580	605	* Unlink a key or keyring from another keyring::
..	..	@@ -859,6 +884,7 @@
859	884	and either the buffer length or the OtherInfo length exceeds the
860	885	allowed length.
861	886
	887	+
862	888	* Restrict keyring linkage::
863	889
864	890	long keyctl(KEYCTL_RESTRICT_KEYRING, key_serial_t keyring,
..	..	@@ -886,8 +912,179 @@
886	912
887	913	One application of restricted keyrings is to verify X.509 certificate
888	914	chains or individual certificate signatures using the asymmetric key type.
889		- See Documentation/crypto/asymmetric-keys.txt for specific restrictions
	915	+ See Documentation/crypto/asymmetric-keys.rst for specific restrictions
890	916	applicable to the asymmetric key type.
	917	+
	918	+
	919	+ * Query an asymmetric key::
	920	+
	921	+ long keyctl(KEYCTL_PKEY_QUERY,
	922	+ key_serial_t key_id, unsigned long reserved,
	923	+ const char *params,
	924	+ struct keyctl_pkey_query *info);
	925	+
	926	+ Get information about an asymmetric key. Specific algorithms and
	927	+ encodings may be queried by using the ``params`` argument. This is a
	928	+ string containing a space- or tab-separated string of key-value pairs.
	929	+ Currently supported keys include ``enc`` and ``hash``. The information
	930	+ is returned in the keyctl_pkey_query struct::
	931	+
	932	+ __u32 supported_ops;
	933	+ __u32 key_size;
	934	+ __u16 max_data_size;
	935	+ __u16 max_sig_size;
	936	+ __u16 max_enc_size;
	937	+ __u16 max_dec_size;
	938	+ __u32 __spare[10];
	939	+
	940	+ ``supported_ops`` contains a bit mask of flags indicating which ops are
	941	+ supported. This is constructed from a bitwise-OR of::
	942	+
	943	+ KEYCTL_SUPPORTS_{ENCRYPT,DECRYPT,SIGN,VERIFY}
	944	+
	945	+ ``key_size`` indicated the size of the key in bits.
	946	+
	947	+ ``max_*_size`` indicate the maximum sizes in bytes of a blob of data to be
	948	+ signed, a signature blob, a blob to be encrypted and a blob to be
	949	+ decrypted.
	950	+
	951	+ ``__spare[]`` must be set to 0. This is intended for future use to hand
	952	+ over one or more passphrases needed unlock a key.
	953	+
	954	+ If successful, 0 is returned. If the key is not an asymmetric key,
	955	+ EOPNOTSUPP is returned.
	956	+
	957	+
	958	+ * Encrypt, decrypt, sign or verify a blob using an asymmetric key::
	959	+
	960	+ long keyctl(KEYCTL_PKEY_ENCRYPT,
	961	+ const struct keyctl_pkey_params *params,
	962	+ const char *info,
	963	+ const void *in,
	964	+ void *out);
	965	+
	966	+ long keyctl(KEYCTL_PKEY_DECRYPT,
	967	+ const struct keyctl_pkey_params *params,
	968	+ const char *info,
	969	+ const void *in,
	970	+ void *out);
	971	+
	972	+ long keyctl(KEYCTL_PKEY_SIGN,
	973	+ const struct keyctl_pkey_params *params,
	974	+ const char *info,
	975	+ const void *in,
	976	+ void *out);
	977	+
	978	+ long keyctl(KEYCTL_PKEY_VERIFY,
	979	+ const struct keyctl_pkey_params *params,
	980	+ const char *info,
	981	+ const void *in,
	982	+ const void *in2);
	983	+
	984	+ Use an asymmetric key to perform a public-key cryptographic operation a
	985	+ blob of data. For encryption and verification, the asymmetric key may
	986	+ only need the public parts to be available, but for decryption and signing
	987	+ the private parts are required also.
	988	+
	989	+ The parameter block pointed to by params contains a number of integer
	990	+ values::
	991	+
	992	+ __s32 key_id;
	993	+ __u32 in_len;
	994	+ __u32 out_len;
	995	+ __u32 in2_len;
	996	+
	997	+ ``key_id`` is the ID of the asymmetric key to be used. ``in_len`` and
	998	+ ``in2_len`` indicate the amount of data in the in and in2 buffers and
	999	+ ``out_len`` indicates the size of the out buffer as appropriate for the
	1000	+ above operations.
	1001	+
	1002	+ For a given operation, the in and out buffers are used as follows::
	1003	+
	1004	+ Operation ID in,in_len out,out_len in2,in2_len
	1005	+ ======================= =============== =============== ===============
	1006	+ KEYCTL_PKEY_ENCRYPT Raw data Encrypted data -
	1007	+ KEYCTL_PKEY_DECRYPT Encrypted data Raw data -
	1008	+ KEYCTL_PKEY_SIGN Raw data Signature -
	1009	+ KEYCTL_PKEY_VERIFY Raw data - Signature
	1010	+
	1011	+ ``info`` is a string of key=value pairs that supply supplementary
	1012	+ information. These include:
	1013	+
	1014	+ ``enc=<encoding>`` The encoding of the encrypted/signature blob. This
	1015	+ can be "pkcs1" for RSASSA-PKCS1-v1.5 or
	1016	+ RSAES-PKCS1-v1.5; "pss" for "RSASSA-PSS"; "oaep" for
	1017	+ "RSAES-OAEP". If omitted or is "raw", the raw output
	1018	+ of the encryption function is specified.
	1019	+
	1020	+ ``hash=<algo>`` If the data buffer contains the output of a hash
	1021	+ function and the encoding includes some indication of
	1022	+ which hash function was used, the hash function can be
	1023	+ specified with this, eg. "hash=sha256".
	1024	+
	1025	+ The ``__spare[]`` space in the parameter block must be set to 0. This is
	1026	+ intended, amongst other things, to allow the passing of passphrases
	1027	+ required to unlock a key.
	1028	+
	1029	+ If successful, encrypt, decrypt and sign all return the amount of data
	1030	+ written into the output buffer. Verification returns 0 on success.
	1031	+
	1032	+
	1033	+ * Watch a key or keyring for changes::
	1034	+
	1035	+ long keyctl(KEYCTL_WATCH_KEY, key_serial_t key, int queue_fd,
	1036	+ const struct watch_notification_filter *filter);
	1037	+
	1038	+ This will set or remove a watch for changes on the specified key or
	1039	+ keyring.
	1040	+
	1041	+ "key" is the ID of the key to be watched.
	1042	+
	1043	+ "queue_fd" is a file descriptor referring to an open pipe which
	1044	+ manages the buffer into which notifications will be delivered.
	1045	+
	1046	+ "filter" is either NULL to remove a watch or a filter specification to
	1047	+ indicate what events are required from the key.
	1048	+
	1049	+ See Documentation/watch_queue.rst for more information.
	1050	+
	1051	+ Note that only one watch may be emplaced for any particular { key,
	1052	+ queue_fd } combination.
	1053	+
	1054	+ Notification records look like::
	1055	+
	1056	+ struct key_notification {
	1057	+ struct watch_notification watch;
	1058	+ __u32 key_id;
	1059	+ __u32 aux;
	1060	+ };
	1061	+
	1062	+ In this, watch::type will be "WATCH_TYPE_KEY_NOTIFY" and subtype will be
	1063	+ one of::
	1064	+
	1065	+ NOTIFY_KEY_INSTANTIATED
	1066	+ NOTIFY_KEY_UPDATED
	1067	+ NOTIFY_KEY_LINKED
	1068	+ NOTIFY_KEY_UNLINKED
	1069	+ NOTIFY_KEY_CLEARED
	1070	+ NOTIFY_KEY_REVOKED
	1071	+ NOTIFY_KEY_INVALIDATED
	1072	+ NOTIFY_KEY_SETATTR
	1073	+
	1074	+ Where these indicate a key being instantiated/rejected, updated, a link
	1075	+ being made in a keyring, a link being removed from a keyring, a keyring
	1076	+ being cleared, a key being revoked, a key being invalidated or a key
	1077	+ having one of its attributes changed (user, group, perm, timeout,
	1078	+ restriction).
	1079	+
	1080	+ If a watched key is deleted, a basic watch_notification will be issued
	1081	+ with "type" set to WATCH_TYPE_META and "subtype" set to
	1082	+ watch_meta_removal_notification. The watchpoint ID will be set in the
	1083	+ "info" field.
	1084	+
	1085	+ This needs to be configured by enabling:
	1086	+
	1087	+ "Provide key/keyring change notifications" (KEY_NOTIFICATIONS)
891	1088
892	1089
893	1090	Kernel Services
..	..	@@ -966,49 +1163,43 @@
966	1163	See also Documentation/security/keys/request-key.rst.
967	1164
968	1165
	1166	+ * To search for a key in a specific domain, call::
	1167	+
	1168	+ struct key request_key_tag(const struct key_type type,
	1169	+ const char *description,
	1170	+ struct key_tag *domain_tag,
	1171	+ const char *callout_info);
	1172	+
	1173	+ This is identical to request_key(), except that a domain tag may be
	1174	+ specifies that causes search algorithm to only match keys matching that
	1175	+ tag. The domain_tag may be NULL, specifying a global domain that is
	1176	+ separate from any nominated domain.
	1177	+
	1178	+
969	1179	* To search for a key, passing auxiliary data to the upcaller, call::
970	1180
971	1181	struct key request_key_with_auxdata(const struct key_type type,
972	1182	const char *description,
	1183	+ struct key_tag *domain_tag,
973	1184	const void *callout_info,
974	1185	size_t callout_len,
975	1186	void *aux);
976	1187
977		- This is identical to request_key(), except that the auxiliary data is
978		- passed to the key_type->request_key() op if it exists, and the callout_info
979		- is a blob of length callout_len, if given (the length may be 0).
	1188	+ This is identical to request_key_tag(), except that the auxiliary data is
	1189	+ passed to the key_type->request_key() op if it exists, and the
	1190	+ callout_info is a blob of length callout_len, if given (the length may be
	1191	+ 0).
980	1192
981	1193
982		- * A key can be requested asynchronously by calling one of::
	1194	+ * To search for a key under RCU conditions, call::
983	1195
984		- struct key request_key_async(const struct key_type type,
985		- const char *description,
986		- const void *callout_info,
987		- size_t callout_len);
	1196	+ struct key request_key_rcu(const struct key_type type,
	1197	+ const char *description,
	1198	+ struct key_tag *domain_tag);
988	1199
989		- or::
990		-
991		- struct key request_key_async_with_auxdata(const struct key_type type,
992		- const char *description,
993		- const char *callout_info,
994		- size_t callout_len,
995		- void *aux);
996		-
997		- which are asynchronous equivalents of request_key() and
998		- request_key_with_auxdata() respectively.
999		-
1000		- These two functions return with the key potentially still under
1001		- construction. To wait for construction completion, the following should be
1002		- called::
1003		-
1004		- int wait_for_key_construction(struct key *key, bool intr);
1005		-
1006		- The function will wait for the key to finish being constructed and then
1007		- invokes key_validate() to return an appropriate value to indicate the state
1008		- of the key (0 indicates the key is usable).
1009		-
1010		- If intr is true, then the wait can be interrupted by a signal, in which
1011		- case error ERESTARTSYS will be returned.
	1200	+ which is similar to request_key_tag() except that it does not check for
	1201	+ keys that are under construction and it will not call out to userspace to
	1202	+ construct a key if it can't find a match.
1012	1203
1013	1204
1014	1205	* When it is no longer required, the key should be released using::
..	..	@@ -1048,11 +1239,13 @@
1048	1239
1049	1240	key_ref_t keyring_search(key_ref_t keyring_ref,
1050	1241	const struct key_type *type,
1051		- const char *description)
	1242	+ const char *description,
	1243	+ bool recurse)
1052	1244
1053		- This searches the keyring tree specified for a matching key. Error ENOKEY
1054		- is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful,
1055		- the returned key will need to be released.
	1245	+ This searches the specified keyring only (recurse == false) or keyring tree
	1246	+ (recurse == true) specified for a matching key. Error ENOKEY is returned
	1247	+ upon failure (use IS_ERR/PTR_ERR to determine). If successful, the returned
	1248	+ key will need to be released.
1056	1249
1057	1250	The possession attribute from the keyring reference is used to control
1058	1251	access through the permissions mask and is propagated to the returned key
..	..	@@ -1483,6 +1676,116 @@
1483	1676	attempted key link operation. If there is no match, -EINVAL is returned.
1484	1677
1485	1678
	1679	+ * ``asym_eds_op`` and ``asym_verify_signature``::
	1680	+
	1681	+ int (asym_eds_op)(struct kernel_pkey_params params,
	1682	+ const void in, void out);
	1683	+ int (asym_verify_signature)(struct kernel_pkey_params params,
	1684	+ const void in, const void in2);
	1685	+
	1686	+ These methods are optional. If provided the first allows a key to be
	1687	+ used to encrypt, decrypt or sign a blob of data, and the second allows a
	1688	+ key to verify a signature.
	1689	+
	1690	+ In all cases, the following information is provided in the params block::
	1691	+
	1692	+ struct kernel_pkey_params {
	1693	+ struct key *key;
	1694	+ const char *encoding;
	1695	+ const char *hash_algo;
	1696	+ char *info;
	1697	+ __u32 in_len;
	1698	+ union {
	1699	+ __u32 out_len;
	1700	+ __u32 in2_len;
	1701	+ };
	1702	+ enum kernel_pkey_operation op : 8;
	1703	+ };
	1704	+
	1705	+ This includes the key to be used; a string indicating the encoding to use
	1706	+ (for instance, "pkcs1" may be used with an RSA key to indicate
	1707	+ RSASSA-PKCS1-v1.5 or RSAES-PKCS1-v1.5 encoding or "raw" if no encoding);
	1708	+ the name of the hash algorithm used to generate the data for a signature
	1709	+ (if appropriate); the sizes of the input and output (or second input)
	1710	+ buffers; and the ID of the operation to be performed.
	1711	+
	1712	+ For a given operation ID, the input and output buffers are used as
	1713	+ follows::
	1714	+
	1715	+ Operation ID in,in_len out,out_len in2,in2_len
	1716	+ ======================= =============== =============== ===============
	1717	+ kernel_pkey_encrypt Raw data Encrypted data -
	1718	+ kernel_pkey_decrypt Encrypted data Raw data -
	1719	+ kernel_pkey_sign Raw data Signature -
	1720	+ kernel_pkey_verify Raw data - Signature
	1721	+
	1722	+ asym_eds_op() deals with encryption, decryption and signature creation as
	1723	+ specified by params->op. Note that params->op is also set for
	1724	+ asym_verify_signature().
	1725	+
	1726	+ Encrypting and signature creation both take raw data in the input buffer
	1727	+ and return the encrypted result in the output buffer. Padding may have
	1728	+ been added if an encoding was set. In the case of signature creation,
	1729	+ depending on the encoding, the padding created may need to indicate the
	1730	+ digest algorithm - the name of which should be supplied in hash_algo.
	1731	+
	1732	+ Decryption takes encrypted data in the input buffer and returns the raw
	1733	+ data in the output buffer. Padding will get checked and stripped off if
	1734	+ an encoding was set.
	1735	+
	1736	+ Verification takes raw data in the input buffer and the signature in the
	1737	+ second input buffer and checks that the one matches the other. Padding
	1738	+ will be validated. Depending on the encoding, the digest algorithm used
	1739	+ to generate the raw data may need to be indicated in hash_algo.
	1740	+
	1741	+ If successful, asym_eds_op() should return the number of bytes written
	1742	+ into the output buffer. asym_verify_signature() should return 0.
	1743	+
	1744	+ A variety of errors may be returned, including EOPNOTSUPP if the operation
	1745	+ is not supported; EKEYREJECTED if verification fails; ENOPKG if the
	1746	+ required crypto isn't available.
	1747	+
	1748	+
	1749	+ * ``asym_query``::
	1750	+
	1751	+ int (asym_query)(const struct kernel_pkey_params params,
	1752	+ struct kernel_pkey_query *info);
	1753	+
	1754	+ This method is optional. If provided it allows information about the
	1755	+ public or asymmetric key held in the key to be determined.
	1756	+
	1757	+ The parameter block is as for asym_eds_op() and co. but in_len and out_len
	1758	+ are unused. The encoding and hash_algo fields should be used to reduce
	1759	+ the returned buffer/data sizes as appropriate.
	1760	+
	1761	+ If successful, the following information is filled in::
	1762	+
	1763	+ struct kernel_pkey_query {
	1764	+ __u32 supported_ops;
	1765	+ __u32 key_size;
	1766	+ __u16 max_data_size;
	1767	+ __u16 max_sig_size;
	1768	+ __u16 max_enc_size;
	1769	+ __u16 max_dec_size;
	1770	+ };
	1771	+
	1772	+ The supported_ops field will contain a bitmask indicating what operations
	1773	+ are supported by the key, including encryption of a blob, decryption of a
	1774	+ blob, signing a blob and verifying the signature on a blob. The following
	1775	+ constants are defined for this::
	1776	+
	1777	+ KEYCTL_SUPPORTS_{ENCRYPT,DECRYPT,SIGN,VERIFY}
	1778	+
	1779	+ The key_size field is the size of the key in bits. max_data_size and
	1780	+ max_sig_size are the maximum raw data and signature sizes for creation and
	1781	+ verification of a signature; max_enc_size and max_dec_size are the maximum
	1782	+ raw data and signature sizes for encryption and decryption. The
	1783	+ max_*_size fields are measured in bytes.
	1784	+
	1785	+ If successful, 0 will be returned. If the key doesn't support this,
	1786	+ EOPNOTSUPP will be returned.
	1787	+
	1788	+
1486	1789	Request-Key Callback Service
1487	1790	============================
1488	1791