Commit 74e2f8d3 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab

docs: fs: fscrypt.rst: get rid of :c:type: tags

The :c:type: tag has problems with Sphinx 3.x, as structs
there should be declared with c:struct.

So, remove them, relying at automarkup.py extension to
convert them into cross-references.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent b30fd8e9
...@@ -436,9 +436,9 @@ FS_IOC_SET_ENCRYPTION_POLICY ...@@ -436,9 +436,9 @@ FS_IOC_SET_ENCRYPTION_POLICY
The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
empty directory or verifies that a directory or regular file already empty directory or verifies that a directory or regular file already
has the specified encryption policy. It takes in a pointer to a has the specified encryption policy. It takes in a pointer to
:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as
fscrypt_policy_v2`, defined as follows:: follows::
#define FSCRYPT_POLICY_V1 0 #define FSCRYPT_POLICY_V1 0
#define FSCRYPT_KEY_DESCRIPTOR_SIZE 8 #define FSCRYPT_KEY_DESCRIPTOR_SIZE 8
...@@ -464,11 +464,11 @@ fscrypt_policy_v2`, defined as follows:: ...@@ -464,11 +464,11 @@ fscrypt_policy_v2`, defined as follows::
This structure must be initialized as follows: This structure must be initialized as follows:
- ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is - ``version`` must be FSCRYPT_POLICY_V1 (0) if
:c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if
is :c:type:`fscrypt_policy_v2`. (Note: we refer to the original struct fscrypt_policy_v2 is used. (Note: we refer to the original
policy version as "v1", though its version code is really 0.) For policy version as "v1", though its version code is really 0.)
new encrypted directories, use v2 policies. For new encrypted directories, use v2 policies.
- ``contents_encryption_mode`` and ``filenames_encryption_mode`` must - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
be set to constants from ``<linux/fscrypt.h>`` which identify the be set to constants from ``<linux/fscrypt.h>`` which identify the
...@@ -508,9 +508,9 @@ This structure must be initialized as follows: ...@@ -508,9 +508,9 @@ This structure must be initialized as follows:
replaced with ``master_key_identifier``, which is longer and cannot replaced with ``master_key_identifier``, which is longer and cannot
be arbitrarily chosen. Instead, the key must first be added using be arbitrarily chosen. Instead, the key must first be added using
`FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier`` `FS_IOC_ADD_ENCRYPTION_KEY`_. Then, the ``key_spec.u.identifier``
the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must the kernel returned in the struct fscrypt_add_key_arg must
be used as the ``master_key_identifier`` in the :c:type:`struct be used as the ``master_key_identifier`` in
fscrypt_policy_v2`. struct fscrypt_policy_v2.
If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
verifies that the file is an empty directory. If so, the specified verifies that the file is an empty directory. If so, the specified
...@@ -590,7 +590,7 @@ FS_IOC_GET_ENCRYPTION_POLICY_EX ...@@ -590,7 +590,7 @@ FS_IOC_GET_ENCRYPTION_POLICY_EX
The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
policy, if any, for a directory or regular file. No additional policy, if any, for a directory or regular file. No additional
permissions are required beyond the ability to open the file. It permissions are required beyond the ability to open the file. It
takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`, takes in a pointer to struct fscrypt_get_policy_ex_arg,
defined as follows:: defined as follows::
struct fscrypt_get_policy_ex_arg { struct fscrypt_get_policy_ex_arg {
...@@ -637,9 +637,8 @@ The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the ...@@ -637,9 +637,8 @@ The FS_IOC_GET_ENCRYPTION_POLICY ioctl can also retrieve the
encryption policy, if any, for a directory or regular file. However, encryption policy, if any, for a directory or regular file. However,
unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_, unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
version. It takes in a pointer directly to a :c:type:`struct version. It takes in a pointer directly to struct fscrypt_policy_v1
fscrypt_policy_v1` rather than a :c:type:`struct rather than struct fscrypt_get_policy_ex_arg.
fscrypt_get_policy_ex_arg`.
The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
...@@ -680,8 +679,7 @@ the filesystem, making all files on the filesystem which were ...@@ -680,8 +679,7 @@ the filesystem, making all files on the filesystem which were
encrypted using that key appear "unlocked", i.e. in plaintext form. encrypted using that key appear "unlocked", i.e. in plaintext form.
It can be executed on any file or directory on the target filesystem, It can be executed on any file or directory on the target filesystem,
but using the filesystem's root directory is recommended. It takes in but using the filesystem's root directory is recommended. It takes in
a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as a pointer to struct fscrypt_add_key_arg, defined as follows::
follows::
struct fscrypt_add_key_arg { struct fscrypt_add_key_arg {
struct fscrypt_key_specifier key_spec; struct fscrypt_key_specifier key_spec;
...@@ -710,17 +708,16 @@ follows:: ...@@ -710,17 +708,16 @@ follows::
__u8 raw[]; __u8 raw[];
}; };
:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized struct fscrypt_add_key_arg must be zeroed, then initialized
as follows: as follows:
- If the key is being added for use by v1 encryption policies, then - If the key is being added for use by v1 encryption policies, then
``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
``key_spec.u.descriptor`` must contain the descriptor of the key ``key_spec.u.descriptor`` must contain the descriptor of the key
being added, corresponding to the value in the being added, corresponding to the value in the
``master_key_descriptor`` field of :c:type:`struct ``master_key_descriptor`` field of struct fscrypt_policy_v1.
fscrypt_policy_v1`. To add this type of key, the calling process To add this type of key, the calling process must have the
must have the CAP_SYS_ADMIN capability in the initial user CAP_SYS_ADMIN capability in the initial user namespace.
namespace.
Alternatively, if the key is being added for use by v2 encryption Alternatively, if the key is being added for use by v2 encryption
policies, then ``key_spec.type`` must contain policies, then ``key_spec.type`` must contain
...@@ -737,12 +734,13 @@ as follows: ...@@ -737,12 +734,13 @@ as follows:
- ``key_id`` is 0 if the raw key is given directly in the ``raw`` - ``key_id`` is 0 if the raw key is given directly in the ``raw``
field. Otherwise ``key_id`` is the ID of a Linux keyring key of field. Otherwise ``key_id`` is the ID of a Linux keyring key of
type "fscrypt-provisioning" whose payload is a :c:type:`struct type "fscrypt-provisioning" whose payload is
fscrypt_provisioning_key_payload` whose ``raw`` field contains the struct fscrypt_provisioning_key_payload whose ``raw`` field contains
raw key and whose ``type`` field matches ``key_spec.type``. Since the raw key and whose ``type`` field matches ``key_spec.type``.
``raw`` is variable-length, the total size of this key's payload Since ``raw`` is variable-length, the total size of this key's
must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the payload must be ``sizeof(struct fscrypt_provisioning_key_payload)``
raw key size. The process must have Search permission on this key. plus the raw key size. The process must have Search permission on
this key.
Most users should leave this 0 and specify the raw key directly. Most users should leave this 0 and specify the raw key directly.
The support for specifying a Linux keyring key is intended mainly to The support for specifying a Linux keyring key is intended mainly to
...@@ -860,8 +858,8 @@ The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master ...@@ -860,8 +858,8 @@ The FS_IOC_REMOVE_ENCRYPTION_KEY ioctl removes a claim to a master
encryption key from the filesystem, and possibly removes the key encryption key from the filesystem, and possibly removes the key
itself. It can be executed on any file or directory on the target itself. It can be executed on any file or directory on the target
filesystem, but using the filesystem's root directory is recommended. filesystem, but using the filesystem's root directory is recommended.
It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`, It takes in a pointer to struct fscrypt_remove_key_arg, defined
defined as follows:: as follows::
struct fscrypt_remove_key_arg { struct fscrypt_remove_key_arg {
struct fscrypt_key_specifier key_spec; struct fscrypt_key_specifier key_spec;
...@@ -956,8 +954,8 @@ FS_IOC_GET_ENCRYPTION_KEY_STATUS ...@@ -956,8 +954,8 @@ FS_IOC_GET_ENCRYPTION_KEY_STATUS
The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
master encryption key. It can be executed on any file or directory on master encryption key. It can be executed on any file or directory on
the target filesystem, but using the filesystem's root directory is the target filesystem, but using the filesystem's root directory is
recommended. It takes in a pointer to a :c:type:`struct recommended. It takes in a pointer to
fscrypt_get_key_status_arg`, defined as follows:: struct fscrypt_get_key_status_arg, defined as follows::
struct fscrypt_get_key_status_arg { struct fscrypt_get_key_status_arg {
/* input */ /* input */
...@@ -1148,10 +1146,10 @@ Implementation details ...@@ -1148,10 +1146,10 @@ Implementation details
Encryption context Encryption context
------------------ ------------------
An encryption policy is represented on-disk by a :c:type:`struct An encryption policy is represented on-disk by
fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`. It is struct fscrypt_context_v1 or struct fscrypt_context_v2. It is up to
up to individual filesystems to decide where to store it, but normally individual filesystems to decide where to store it, but normally it
it would be stored in a hidden extended attribute. It should *not* be would be stored in a hidden extended attribute. It should *not* be
exposed by the xattr-related system calls such as getxattr() and exposed by the xattr-related system calls such as getxattr() and
setxattr() because of the special semantics of the encryption xattr. setxattr() because of the special semantics of the encryption xattr.
(In particular, there would be much confusion if an encryption policy (In particular, there would be much confusion if an encryption policy
...@@ -1249,8 +1247,8 @@ a strong "hash" of the ciphertext filename, along with the optional ...@@ -1249,8 +1247,8 @@ a strong "hash" of the ciphertext filename, along with the optional
filesystem-specific hash(es) needed for directory lookups. This filesystem-specific hash(es) needed for directory lookups. This
allows the filesystem to still, with a high degree of confidence, map allows the filesystem to still, with a high degree of confidence, map
the filename given in ->lookup() back to a particular directory entry the filename given in ->lookup() back to a particular directory entry
that was previously listed by readdir(). See :c:type:`struct that was previously listed by readdir(). See
fscrypt_nokey_name` in the source for more details. struct fscrypt_nokey_name in the source for more details.
Note that the precise way that filenames are presented to userspace Note that the precise way that filenames are presented to userspace
without the key is subject to change in the future. It is only meant without the key is subject to change in the future. It is only meant
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment