From: David Howells <dhowells@redhat.com> To: torvalds@linux-foundation.org Cc: dhowells@redhat.com, Greg Kroah-Hartman <gregkh@linuxfoundation.org>, Casey Schaufler <casey@schaufler-ca.com>, Stephen Smalley <sds@tycho.nsa.gov>, nicolas.dichtel@6wind.com, raven@themaw.net, Christian Brauner <christian@brauner.io>, dhowells@redhat.com, keyrings@vger.kernel.org, linux-usb@vger.kernel.org, linux-block@vger.kernel.org, linux-security-module@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-api@vger.kernel.org, linux-security-module@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RFC PATCH 03/14] security: Add a hook for the point of notification insertion [ver #2] Date: Thu, 07 Nov 2019 13:35:47 +0000 [thread overview] Message-ID: <157313374753.29677.10499095666351592097.stgit@warthog.procyon.org.uk> (raw) In-Reply-To: <157313371694.29677.15388731274912671071.stgit@warthog.procyon.org.uk> Add a security hook that allows an LSM to rule on whether a notification message is allowed to be inserted into a particular watch queue. The hook is given the following information: (1) The credentials of the triggerer (which may be init_cred for a system notification, eg. a hardware error). (2) The credentials of the whoever set the watch. (3) The notification message. Signed-off-by: David Howells <dhowells@redhat.com> cc: Casey Schaufler <casey@schaufler-ca.com> cc: Stephen Smalley <sds@tycho.nsa.gov> cc: linux-security-module@vger.kernel.org --- include/linux/lsm_hooks.h | 14 ++++++++++++++ include/linux/security.h | 15 ++++++++++++++- security/security.c | 9 +++++++++ 3 files changed, 37 insertions(+), 1 deletion(-) diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h index d62e92b768c4..8e1cbc27fc62 100644 --- a/include/linux/lsm_hooks.h +++ b/include/linux/lsm_hooks.h @@ -1427,6 +1427,12 @@ * Check to see if a process is allowed to watch for event notifications * from devices (as a global set). * + * @post_notification: + * Check to see if a watch notification can be posted to a particular + * queue. + * @w_cred: The credentials of the whoever set the watch. + * @cred: The event-triggerer's credentials + * @n: The notification being posted * * Security hooks for using the eBPF maps and programs functionalities through * eBPF syscalls. @@ -1716,6 +1722,11 @@ union security_list_options { #ifdef CONFIG_DEVICE_NOTIFICATIONS int (*watch_devices)(void); #endif +#ifdef CONFIG_WATCH_QUEUE + int (*post_notification)(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n); +#endif #ifdef CONFIG_SECURITY_NETWORK int (*unix_stream_connect)(struct sock *sock, struct sock *other, @@ -2001,6 +2012,9 @@ struct security_hook_heads { #ifdef CONFIG_DEVICE_NOTIFICATIONS struct hlist_head watch_devices; #endif +#ifdef CONFIG_WATCH_QUEUE + struct hlist_head post_notification; +#endif /* CONFIG_WATCH_QUEUE */ #ifdef CONFIG_SECURITY_NETWORK struct hlist_head unix_stream_connect; struct hlist_head unix_may_send; diff --git a/include/linux/security.h b/include/linux/security.h index 5d1867772022..ee98e020c749 100644 --- a/include/linux/security.h +++ b/include/linux/security.h @@ -57,6 +57,8 @@ struct mm_struct; struct fs_context; struct fs_parameter; enum fs_value_type; +struct watch; +struct watch_notification; /* Default (no) options for the capable function */ #define CAP_OPT_NONE 0x0 @@ -1287,6 +1289,18 @@ static inline int security_watch_devices(void) return 0; } #endif +#if defined(CONFIG_SECURITY) && defined(CONFIG_WATCH_QUEUE) +int security_post_notification(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n); +#else +static inline int security_post_notification(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n) +{ + return 0; +} +#endif #ifdef CONFIG_SECURITY_NETWORK @@ -1912,4 +1926,3 @@ static inline void security_bpf_prog_free(struct bpf_prog_aux *aux) #endif /* CONFIG_BPF_SYSCALL */ #endif /* ! __LINUX_SECURITY_H */ - diff --git a/security/security.c b/security/security.c index 4f970716fa6c..c9d5c3d5472a 100644 --- a/security/security.c +++ b/security/security.c @@ -1956,6 +1956,15 @@ int security_inode_getsecctx(struct inode *inode, void **ctx, u32 *ctxlen) } EXPORT_SYMBOL(security_inode_getsecctx); +#ifdef CONFIG_WATCH_QUEUE +int security_post_notification(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n) +{ + return call_int_hook(post_notification, 0, w_cred, cred, n); +} +#endif /* CONFIG_WATCH_QUEUE */ + #ifdef CONFIG_KEY_NOTIFICATIONS int security_watch_key(struct key *key) {
WARNING: multiple messages have this Message-ID
From: David Howells <dhowells@redhat.com> To: torvalds@linux-foundation.org Cc: dhowells@redhat.com, Greg Kroah-Hartman <gregkh@linuxfoundation.org>, Casey Schaufler <casey@schaufler-ca.com>, Stephen Smalley <sds@tycho.nsa.gov>, nicolas.dichtel@6wind.com, raven@themaw.net, Christian Brauner <christian@brauner.io>dhowells@redhat.com, keyrings@vger.kernel.org, linux-usb@vger.kernel.org, linux-block@vger.kernel.org, linux-security-module@vger.kernel.org, linux-fsdevel@vger.kernel.org@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RFC PATCH 03/14] security: Add a hook for the point of notification insertion [ver #2] Date: Thu, 07 Nov 2019 13:35:47 +0000 [thread overview] Message-ID: <157313374753.29677.10499095666351592097.stgit@warthog.procyon.org.uk> (raw) In-Reply-To: <157313371694.29677.15388731274912671071.stgit@warthog.procyon.org.uk> Add a security hook that allows an LSM to rule on whether a notification message is allowed to be inserted into a particular watch queue. The hook is given the following information: (1) The credentials of the triggerer (which may be init_cred for a system notification, eg. a hardware error). (2) The credentials of the whoever set the watch. (3) The notification message. Signed-off-by: David Howells <dhowells@redhat.com> cc: Casey Schaufler <casey@schaufler-ca.com> cc: Stephen Smalley <sds@tycho.nsa.gov> cc: linux-security-module@vger.kernel.org --- include/linux/lsm_hooks.h | 14 ++++++++++++++ include/linux/security.h | 15 ++++++++++++++- security/security.c | 9 +++++++++ 3 files changed, 37 insertions(+), 1 deletion(-) diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h index d62e92b768c4..8e1cbc27fc62 100644 --- a/include/linux/lsm_hooks.h +++ b/include/linux/lsm_hooks.h @@ -1427,6 +1427,12 @@ * Check to see if a process is allowed to watch for event notifications * from devices (as a global set). * + * @post_notification: + * Check to see if a watch notification can be posted to a particular + * queue. + * @w_cred: The credentials of the whoever set the watch. + * @cred: The event-triggerer's credentials + * @n: The notification being posted * * Security hooks for using the eBPF maps and programs functionalities through * eBPF syscalls. @@ -1716,6 +1722,11 @@ union security_list_options { #ifdef CONFIG_DEVICE_NOTIFICATIONS int (*watch_devices)(void); #endif +#ifdef CONFIG_WATCH_QUEUE + int (*post_notification)(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n); +#endif #ifdef CONFIG_SECURITY_NETWORK int (*unix_stream_connect)(struct sock *sock, struct sock *other, @@ -2001,6 +2012,9 @@ struct security_hook_heads { #ifdef CONFIG_DEVICE_NOTIFICATIONS struct hlist_head watch_devices; #endif +#ifdef CONFIG_WATCH_QUEUE + struct hlist_head post_notification; +#endif /* CONFIG_WATCH_QUEUE */ #ifdef CONFIG_SECURITY_NETWORK struct hlist_head unix_stream_connect; struct hlist_head unix_may_send; diff --git a/include/linux/security.h b/include/linux/security.h index 5d1867772022..ee98e020c749 100644 --- a/include/linux/security.h +++ b/include/linux/security.h @@ -57,6 +57,8 @@ struct mm_struct; struct fs_context; struct fs_parameter; enum fs_value_type; +struct watch; +struct watch_notification; /* Default (no) options for the capable function */ #define CAP_OPT_NONE 0x0 @@ -1287,6 +1289,18 @@ static inline int security_watch_devices(void) return 0; } #endif +#if defined(CONFIG_SECURITY) && defined(CONFIG_WATCH_QUEUE) +int security_post_notification(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n); +#else +static inline int security_post_notification(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n) +{ + return 0; +} +#endif #ifdef CONFIG_SECURITY_NETWORK @@ -1912,4 +1926,3 @@ static inline void security_bpf_prog_free(struct bpf_prog_aux *aux) #endif /* CONFIG_BPF_SYSCALL */ #endif /* ! __LINUX_SECURITY_H */ - diff --git a/security/security.c b/security/security.c index 4f970716fa6c..c9d5c3d5472a 100644 --- a/security/security.c +++ b/security/security.c @@ -1956,6 +1956,15 @@ int security_inode_getsecctx(struct inode *inode, void **ctx, u32 *ctxlen) } EXPORT_SYMBOL(security_inode_getsecctx); +#ifdef CONFIG_WATCH_QUEUE +int security_post_notification(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n) +{ + return call_int_hook(post_notification, 0, w_cred, cred, n); +} +#endif /* CONFIG_WATCH_QUEUE */ + #ifdef CONFIG_KEY_NOTIFICATIONS int security_watch_key(struct key *key) {
WARNING: multiple messages have this Message-ID
From: David Howells <dhowells@redhat.com> To: torvalds@linux-foundation.org Cc: dhowells@redhat.com, Greg Kroah-Hartman <gregkh@linuxfoundation.org>, Casey Schaufler <casey@schaufler-ca.com>, Stephen Smalley <sds@tycho.nsa.gov>, nicolas.dichtel@6wind.com, raven@themaw.net, Christian Brauner <christian@brauner.io>dhowells@redhat.com, keyrings@vger.kernel.org, linux-usb@vger.kernel.org, linux-block@vger.kernel.org, linux-security-module@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-api@vger.kernel.orglinux-security-module@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [RFC PATCH 03/14] security: Add a hook for the point of notification insertion [ver #2] Date: Thu, 07 Nov 2019 13:35:47 +0000 [thread overview] Message-ID: <157313374753.29677.10499095666351592097.stgit@warthog.procyon.org.uk> (raw) In-Reply-To: <157313371694.29677.15388731274912671071.stgit@warthog.procyon.org.uk> Add a security hook that allows an LSM to rule on whether a notification message is allowed to be inserted into a particular watch queue. The hook is given the following information: (1) The credentials of the triggerer (which may be init_cred for a system notification, eg. a hardware error). (2) The credentials of the whoever set the watch. (3) The notification message. Signed-off-by: David Howells <dhowells@redhat.com> cc: Casey Schaufler <casey@schaufler-ca.com> cc: Stephen Smalley <sds@tycho.nsa.gov> cc: linux-security-module@vger.kernel.org --- include/linux/lsm_hooks.h | 14 ++++++++++++++ include/linux/security.h | 15 ++++++++++++++- security/security.c | 9 +++++++++ 3 files changed, 37 insertions(+), 1 deletion(-) diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h index d62e92b768c4..8e1cbc27fc62 100644 --- a/include/linux/lsm_hooks.h +++ b/include/linux/lsm_hooks.h @@ -1427,6 +1427,12 @@ * Check to see if a process is allowed to watch for event notifications * from devices (as a global set). * + * @post_notification: + * Check to see if a watch notification can be posted to a particular + * queue. + * @w_cred: The credentials of the whoever set the watch. + * @cred: The event-triggerer's credentials + * @n: The notification being posted * * Security hooks for using the eBPF maps and programs functionalities through * eBPF syscalls. @@ -1716,6 +1722,11 @@ union security_list_options { #ifdef CONFIG_DEVICE_NOTIFICATIONS int (*watch_devices)(void); #endif +#ifdef CONFIG_WATCH_QUEUE + int (*post_notification)(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n); +#endif #ifdef CONFIG_SECURITY_NETWORK int (*unix_stream_connect)(struct sock *sock, struct sock *other, @@ -2001,6 +2012,9 @@ struct security_hook_heads { #ifdef CONFIG_DEVICE_NOTIFICATIONS struct hlist_head watch_devices; #endif +#ifdef CONFIG_WATCH_QUEUE + struct hlist_head post_notification; +#endif /* CONFIG_WATCH_QUEUE */ #ifdef CONFIG_SECURITY_NETWORK struct hlist_head unix_stream_connect; struct hlist_head unix_may_send; diff --git a/include/linux/security.h b/include/linux/security.h index 5d1867772022..ee98e020c749 100644 --- a/include/linux/security.h +++ b/include/linux/security.h @@ -57,6 +57,8 @@ struct mm_struct; struct fs_context; struct fs_parameter; enum fs_value_type; +struct watch; +struct watch_notification; /* Default (no) options for the capable function */ #define CAP_OPT_NONE 0x0 @@ -1287,6 +1289,18 @@ static inline int security_watch_devices(void) return 0; } #endif +#if defined(CONFIG_SECURITY) && defined(CONFIG_WATCH_QUEUE) +int security_post_notification(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n); +#else +static inline int security_post_notification(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n) +{ + return 0; +} +#endif #ifdef CONFIG_SECURITY_NETWORK @@ -1912,4 +1926,3 @@ static inline void security_bpf_prog_free(struct bpf_prog_aux *aux) #endif /* CONFIG_BPF_SYSCALL */ #endif /* ! __LINUX_SECURITY_H */ - diff --git a/security/security.c b/security/security.c index 4f970716fa6c..c9d5c3d5472a 100644 --- a/security/security.c +++ b/security/security.c @@ -1956,6 +1956,15 @@ int security_inode_getsecctx(struct inode *inode, void **ctx, u32 *ctxlen) } EXPORT_SYMBOL(security_inode_getsecctx); +#ifdef CONFIG_WATCH_QUEUE +int security_post_notification(const struct cred *w_cred, + const struct cred *cred, + struct watch_notification *n) +{ + return call_int_hook(post_notification, 0, w_cred, cred, n); +} +#endif /* CONFIG_WATCH_QUEUE */ + #ifdef CONFIG_KEY_NOTIFICATIONS int security_watch_key(struct key *key) {
next prev parent reply other threads:[~2019-11-07 13:35 UTC|newest] Thread overview: 110+ messages / expand[flat|nested] mbox.gz Atom feed top 2019-11-07 13:35 [RFC PATCH 00/14] pipe: Keyrings, Block and USB notifications " David Howells 2019-11-07 13:35 ` David Howells 2019-11-07 13:35 ` David Howells 2019-11-07 13:35 ` [RFC PATCH 01/14] uapi: General notification queue definitions " David Howells 2019-11-07 13:35 ` David Howells 2019-11-07 13:35 ` David Howells 2019-11-07 13:35 ` [RFC PATCH 02/14] security: Add hooks to rule on setting a watch " David Howells 2019-11-07 13:35 ` David Howells 2019-11-07 13:35 ` David Howells 2019-11-07 13:35 ` David Howells [this message] 2019-11-07 13:35 ` [RFC PATCH 03/14] security: Add a hook for the point of notification insertion " David Howells 2019-11-07 13:35 ` David Howells 2019-11-07 13:35 ` [RFC PATCH 04/14] pipe: Add O_NOTIFICATION_PIPE " David Howells 2019-11-07 13:35 ` David Howells 2019-11-07 13:35 ` David Howells 2019-11-07 18:16 ` Andy Lutomirski 2019-11-07 18:16 ` Andy Lutomirski 2019-11-07 18:48 ` David Howells 2019-11-08 5:06 ` Andy Lutomirski 2019-11-08 5:06 ` Andy Lutomirski 2019-11-08 6:42 ` David Howells 2019-11-07 13:36 ` [RFC PATCH 05/14] pipe: Add general notification queue support " David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:36 ` [RFC PATCH 06/14] keys: Add a notification facility " David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:36 ` [RFC PATCH 07/14] Add sample notification program " David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:36 ` [RFC PATCH 08/14] pipe: Allow buffers to be marked read-whole-or-error for notifications " David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 18:15 ` Andy Lutomirski 2019-11-07 18:15 ` [RFC PATCH 08/14] pipe: Allow buffers to be marked read-whole-or-error for notifications [ver #2 Andy Lutomirski 2019-11-07 18:23 ` [RFC PATCH 08/14] pipe: Allow buffers to be marked read-whole-or-error for notifications [ver #2] David Howells 2019-11-07 18:23 ` [RFC PATCH 08/14] pipe: Allow buffers to be marked read-whole-or-error for notifications [ver #2 David Howells 2019-11-07 13:36 ` [RFC PATCH 09/14] pipe: Add notification lossage handling [ver #2] David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:36 ` [RFC PATCH 10/14] Add a general, global device notification watch list " David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:36 ` David Howells 2019-11-07 13:37 ` [RFC PATCH 11/14] block: Add block layer notifications " David Howells 2019-11-07 13:37 ` David Howells 2019-11-07 13:37 ` David Howells 2019-11-07 13:37 ` [RFC PATCH 12/14] usb: Add USB subsystem " David Howells 2019-11-07 13:37 ` David Howells 2019-11-07 13:37 ` David Howells 2019-11-07 13:37 ` [RFC PATCH 13/14] selinux: Implement the watch_key security hook " David Howells 2019-11-07 13:37 ` David Howells 2019-11-07 13:37 ` David Howells 2019-11-07 13:37 ` [RFC PATCH 14/14] smack: Implement the watch_key and post_notification hooks " David Howells 2019-11-07 13:37 ` David Howells 2019-11-07 13:37 ` David Howells 2019-11-07 17:16 ` [RFC PATCH 05/14] pipe: Add general notification queue support " David Howells 2020-01-15 13:30 [RFC PATCH 00/14] pipe: Keyrings, Block and USB notifications [ver #3] David Howells 2020-01-15 13:30 ` David Howells 2020-01-15 13:30 ` David Howells 2020-01-15 13:30 ` [RFC PATCH 01/14] uapi: General notification queue definitions " David Howells 2020-01-15 13:30 ` David Howells 2020-01-15 13:30 ` David Howells 2020-01-15 13:30 ` [RFC PATCH 02/14] security: Add hooks to rule on setting a watch " David Howells 2020-01-15 13:30 ` David Howells 2020-01-15 13:30 ` David Howells 2020-01-15 13:31 ` [RFC PATCH 03/14] security: Add a hook for the point of notification insertion " David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` [RFC PATCH 04/14] pipe: Add O_NOTIFICATION_PIPE " David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` [RFC PATCH 05/14] pipe: Add general notification queue support " David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` [RFC PATCH 06/14] keys: Add a notification facility " David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` [RFC PATCH 07/14] Add sample notification program " David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` David Howells 2020-01-26 15:47 ` Guenter Roeck 2020-01-26 15:47 ` Guenter Roeck 2020-01-26 15:47 ` Guenter Roeck 2020-01-15 13:31 ` [RFC PATCH 08/14] pipe: Allow buffers to be marked read-whole-or-error for notifications " David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` [RFC PATCH 09/14] pipe: Add notification lossage handling " David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:31 ` David Howells 2020-01-15 13:32 ` [RFC PATCH 10/14] Add a general, global device notification watch list " David Howells 2020-01-15 13:32 ` David Howells 2020-01-15 13:32 ` David Howells 2020-01-15 13:32 ` [RFC PATCH 11/14] block: Add block layer notifications " David Howells 2020-01-15 13:32 ` David Howells 2020-01-15 13:32 ` David Howells 2020-01-15 13:32 ` [RFC PATCH 12/14] usb: Add USB subsystem " David Howells 2020-01-15 13:32 ` David Howells 2020-01-15 13:32 ` David Howells 2020-01-15 13:32 ` [RFC PATCH 13/14] selinux: Implement the watch_key security hook " David Howells 2020-01-15 13:32 ` David Howells 2020-01-15 13:32 ` David Howells 2020-01-15 13:32 ` [RFC PATCH 14/14] smack: Implement the watch_key and post_notification hooks " David Howells 2020-01-15 13:32 ` David Howells 2020-01-15 13:32 ` David Howells 2020-01-15 20:10 ` [RFC PATCH 00/14] pipe: Keyrings, Block and USB notifications " Linus Torvalds 2020-01-15 20:10 ` Linus Torvalds 2020-02-11 0:56 ` Andres Freund 2020-02-11 0:56 ` Andres Freund 2020-01-15 21:07 ` David Howells 2020-01-15 21:07 ` David Howells
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=157313374753.29677.10499095666351592097.stgit@warthog.procyon.org.uk \ --to=dhowells@redhat.com \ --cc=casey@schaufler-ca.com \ --cc=christian@brauner.io \ --cc=gregkh@linuxfoundation.org \ --cc=keyrings@vger.kernel.org \ --cc=linux-api@vger.kernel.org \ --cc=linux-block@vger.kernel.org \ --cc=linux-fsdevel@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux-security-module@vger.kernel.org \ --cc=linux-usb@vger.kernel.org \ --cc=nicolas.dichtel@6wind.com \ --cc=raven@themaw.net \ --cc=sds@tycho.nsa.gov \ --cc=torvalds@linux-foundation.org \ --subject='Re: [RFC PATCH 03/14] security: Add a hook for the point of notification insertion [ver #2]' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.