PM: hibernate: encrypted snapshots under lockdown
Subsystems (5)
v3 cover PM: hibernate: encrypted snapshots under lockdown
Lockdown disables hibernation because resume restores kernel memory from an image userspace can modify. This also prevents a TPM-backed uswsusp implementation from using /dev/snapshot under lockdown.
This series encrypts and authenticates the snapshot in the kernel. The kernel generates the image key and wraps it with a seed supplied by trusted early userspace. TPM policy and unsealing remain outside the PM code.
The seed interface is first-writer-wins and does not provide freshness. Trusted early userspace must provision it before untrusted privileged code runs and enforce the required TPM policy, rollback protection and recovery handling.
Tested on StarFighter MTL with Secure Boot disabled, integrity lockdown selected manually and a TPM-sealed seed. Keyless and user-key S4 cycles resumed the same process and boot ID with the swap header restored. Corrupted wrapped data, invalid magic, a corrupted complete-chunk tag and a wrong user key were rejected. On exact v3, the user-key cycle and the allocation, free and reallocation path used by swap-write confinement also passed.
Previous version as it was updated whist waiting review:
https://lore.kernel.org/all/[email protected]/
Changes in v3:
- Rebase on current upstream master.
- Preserve and validate the saved encrypted metadata boundary on resume.
- Drain buffered metadata before a late user-key transition.
- Reserve enough encrypted image space if userspace adds a user key after querying the image size.
- Apply swap-write confinement before enabling the lockdown exception, while preserving the ordinary availability check which routes lockdown writes to the confined path.
- Account the pages actually allocated through the snapshot API instead of assuming a userspace swap-map format.
- Document the first-writer, anti-replay and userspace I/O requirements.
- Remove an unused swap reverse-mapping helper and tighten local naming.
Changes in v2:
- Keep raw writes to active swap blocked under lockdown.
- Track encrypted snapshot bytes and header writes before allowing lockdown-time image writes.
- Split the encrypted stream at the metadata boundary only when a user-key transition is used.
- Return -EFAULT for userspace copy failures.
- Document resume meta_size handling.
Evan Green (1):
PM: hibernate: add seed-wrapped encrypted snapshots
Sean Rhodes (3):
PM: hibernate: confine encrypted snapshot writes
PM: hibernate: permit encrypted snapshot device under lockdown
PM: hibernate: document encrypted snapshot seed ABI
Documentation/ABI/testing/sysfs-power | 18 + Documentation/power/userland-swsusp.rst | 33 + block/fops.c | 58 +- include/linux/suspend.h | 24 + include/linux/swap.h | 9 + include/uapi/linux/suspend_ioctls.h | 31 +- kernel/power/Kconfig | 15 + kernel/power/Makefile | 1 + kernel/power/hibernate.c | 32 + kernel/power/power.h | 3 + kernel/power/snapenc.c | 952 ++++++++++++++++++++++++ kernel/power/snapshot.c | 5 + kernel/power/swap.c | 87 +++ kernel/power/user.c | 272 ++++++- kernel/power/user.h | 150 ++++ mm/swapfile.c | 25 + 16 files changed, 1683 insertions(+), 32 deletions(-) create mode 100644 kernel/power/snapenc.c create mode 100644 kernel/power/user.h
PATCH RESEND v3 1/4 PM: hibernate: add seed-wrapped encrypted snapshots
From: Evan Green <[email protected]>
Encrypt and authenticate uswsusp hibernation images in the kernel so userspace cannot tamper with the image that will be restored as kernel memory.
The image data is protected with gcm(aes) in 16-page chunks. SNAPSHOT_ENABLE_ENCRYPTION enables the encrypted read/write paths and returns an opaque wrapped image-key blob with the starting nonce on suspend. On resume, userspace provides the same blob and nonce after trusted early userspace has written the same 32-byte seed to /sys/power/snapshot_seed.
The plaintext image key is generated and unwrapped inside the kernel. The wrapping key is derived from the locked seed, leaving TPM PCR policy and seed unsealing to early userspace rather than adding TPM or trusted-key state to PM code.
SNAPSHOT_SET_USER_KEY lets userspace fold extra key material into the data encryption key after the metadata area has been read or written.
Tested on StarFighter MTL with a TPM-sealed seed: complete keyless and user-key encrypted uswsusp cycles resumed the same process and boot ID. Corrupted wrapped data, invalid blob magic, a corrupted complete-chunk tag and a wrong user key were rejected.
--- Documentation/power/userland-swsusp.rst | 16 + include/uapi/linux/suspend_ioctls.h | 31 +- kernel/power/Kconfig | 15 + kernel/power/Makefile | 1 + kernel/power/hibernate.c | 24 + kernel/power/power.h | 1 + kernel/power/snapenc.c | 952 ++++++++++++++++++++++++ kernel/power/snapshot.c | 5 + kernel/power/user.c | 59 +- kernel/power/user.h | 139 ++++ 10 files changed, 1225 insertions(+), 18 deletions(-) create mode 100644 kernel/power/snapenc.c create mode 100644 kernel/power/user.h
Documentation/power/userland-swsusp.rst +16 -0
@@ -115,6 +115,22 @@ SNAPSHOT_S2RAM to resume the system from RAM if there's enough battery power or restore its state on the basis of the saved suspend image otherwise) +SNAPSHOT_ENABLE_ENCRYPTION + Enables encryption of the hibernate image within the kernel. Upon suspend + (ie when the snapshot device was opened for reading), returns a blob + representing the random encryption key the kernel created to encrypt the + hibernate image with. Upon resume (ie when the snapshot device was opened + for writing), receives a blob from usermode containing the key material + previously returned during hibernate. + +SNAPSHOT_SET_USER_KEY + Mixes additional user key material into the data portion of an encrypted + hibernate image. The ioctl argument points to struct uswsusp_user_key. + key_len must be between 8 and USWSUSP_USER_KEY_SIZE bytes, and reserved + must be zero. The kernel writes meta_size with the encrypted metadata + size that userspace may transfer before providing the user key during + resume. + The device's read() operation can be used to transfer the snapshot image from the kernel. It has the following limitations:
include/uapi/linux/suspend_ioctls.h +30 -1
@@ -13,6 +13,31 @@ struct resume_swap_area {__u32 dev; } __attribute__((packed)); +#define USWSUSP_KEY_NONCE_SIZE 16 +#define USWSUSP_USER_KEY_SIZE 32 + +/* +* This structure is used to pass the opaque wrapped hibernate image +* encryption key and starting nonce in either direction. +*/ +struct uswsusp_key_blob { +__u32 blob_len; +__u8 blob[512 ]; + __u8 nonce[USWSUSP_KEY_NONCE_SIZE] __kernel_nonstring; +} __attribute__((packed)); + +/* +* Allow user mode to fold in key material for the data portion of the hibernate +* image. +*/ +struct uswsusp_user_key { +/* Kernel returns the metadata size; resume passes the saved value in. */ +__u64 meta_size; +__u32 key_len; +__u32 reserved; + __u8 key[USWSUSP_USER_KEY_SIZE] __kernel_nonstring; +} __attribute__((packed)); +#define SNAPSHOT_IOC_MAGIC '3'#define SNAPSHOT_FREEZE _IO(SNAPSHOT_IOC_MAGIC, 1)#define SNAPSHOT_UNFREEZE _IO(SNAPSHOT_IOC_MAGIC, 2)
@@ -29,6 +54,10 @@ struct resume_swap_area {#define SNAPSHOT_PREF_IMAGE_SIZE _IO(SNAPSHOT_IOC_MAGIC, 18)#define SNAPSHOT_AVAIL_SWAP_SIZE _IOR(SNAPSHOT_IOC_MAGIC, 19, __kernel_loff_t)#define SNAPSHOT_ALLOC_SWAP_PAGE _IOR(SNAPSHOT_IOC_MAGIC, 20, __kernel_loff_t) -#define SNAPSHOT_IOC_MAXNR 20 +#define SNAPSHOT_ENABLE_ENCRYPTION _IOWR(SNAPSHOT_IOC_MAGIC, 21, \ + struct uswsusp_key_blob) +#define SNAPSHOT_SET_USER_KEY _IOWR(SNAPSHOT_IOC_MAGIC, 22, \ + struct uswsusp_user_key) +#define SNAPSHOT_IOC_MAXNR 22#endif /* _LINUX_SUSPEND_IOCTLS_H */
kernel/power/Kconfig +15 -0
@@ -115,6 +115,21 @@ config HIBERNATION_DEF_COMP help Default compressor to be used for hibernation. +config ENCRYPTED_HIBERNATION + bool "Encryption support for userspace snapshots" + depends on HIBERNATION_SNAPSHOT_DEV + select CRYPTO_AES + select CRYPTO_GCM + select CRYPTO_LIB_SHA256 + help + Enable support for kernel-based encryption of hibernation snapshots + created by uswsusp tools. A trusted early userspace component must + provide the snapshot encryption seed before enabling encryption. + + Say N if userspace handles the image encryption. + + If in doubt, say N. + config PM_STD_PARTITION string "Default resume partition" depends on HIBERNATION
kernel/power/Makefile +1 -0
@@ -16,6 +16,7 @@ obj-$(CONFIG_SUSPEND) += suspend.o obj-$(CONFIG_PM_TEST_SUSPEND) += suspend_test.o obj-$(CONFIG_HIBERNATION) += hibernate.o snapshot.o swap.o obj-$(CONFIG_HIBERNATION_SNAPSHOT_DEV) += user.o +obj-$(CONFIG_ENCRYPTED_HIBERNATION) += snapenc.o obj-$(CONFIG_PM_AUTOSLEEP) += autosleep.o obj-$(CONFIG_PM_WAKELOCKS) += wakelock.o
kernel/power/hibernate.c +24 -0
@@ -36,6 +36,7 @@#include <trace/events/power.h> #include "power.h" +#include "user.h" static int nocompress;
@@ -1376,12 +1377,35 @@ static ssize_t reserved_size_store(struct kobject *kobj,power_attr (reserved_size); +#ifdef CONFIG_ENCRYPTED_HIBERNATION +static ssize_t snapshot_seed_store (struct kobject *kobj, +struct kobj_attribute *attr, +const char *buf,size_t n) +{ +int ret; + + ret =snapshot_store_encryption_seed (buf, n); +return ret ? ret : n; +} + +static struct kobj_attribute snapshot_seed_attr = { + .attr = { + .name ="snapshot_seed" , + .mode =0200 , + }, + .store = snapshot_seed_store, +}; +#endif +static struct attribute *g[] = { &disk_attr.attr, &resume_offset_attr.attr, &resume_attr.attr, &image_size_attr.attr, &reserved_size_attr.attr, +#ifdef CONFIG_ENCRYPTED_HIBERNATION + &snapshot_seed_attr.attr, +#endifNULL , };
kernel/power/power.h +1 -0
@@ -160,6 +160,7 @@ struct snapshot_handle {extern unsigned int snapshot_additional_pages (struct zone *zone);extern unsigned long snapshot_get_image_size (void ); +unsigned long snapshot_get_meta_page_count (void );extern int snapshot_read_next (struct snapshot_handle *handle);extern int snapshot_write_next (struct snapshot_handle *handle);int snapshot_write_finalize (struct snapshot_handle *handle);
kernel/power/snapenc.c new file +952 -0
952 lines not on this page · raw message
kernel/power/snapshot.c +5 -0
@@ -2177,6 +2177,11 @@ unsigned long snapshot_get_image_size(void)return nr_copy_pages + nr_meta_pages +1 ; } +unsigned long snapshot_get_meta_page_count (void ) +{ +return nr_meta_pages +1 ; +} +static int init_header (struct swsusp_info *info) {memset (info,0 ,sizeof (struct swsusp_info ));
kernel/power/user.c +42 -17
142 lines not on this page · raw message
kernel/power/user.h new file +139 -0
139 lines not on this page · raw message
PATCH RESEND v3 2/4 PM: hibernate: confine encrypted snapshot writes
In reply to Sean RhodesUserspace writes a uswsusp image through the normal block path. Before allowing encrypted hibernation under lockdown, restrict direct writes to the process that owns the active snapshot, the swap extents allocated through the snapshot API, the recorded swap-header page, and the total number of pages allocated for the image.
Apply the checks to the active swap backend even when its block-device inode is not itself marked as swap. Require synchronous buffered writes so reservation accounting follows completed I/O, and release reservations for partial writes.
--- block/fops.c | 58 ++++++++--- include/linux/suspend.h | 24 +++++ include/linux/swap.h | 9 ++ kernel/power/power.h | 1 + kernel/power/swap.c | 87 +++++++++++++++++ kernel/power/user.c | 211 ++++++++++++++++++++++++++++++++++++++++ kernel/power/user.h | 11 +++ mm/swapfile.c | 25 +++++ 8 files changed, 413 insertions(+), 13 deletions(-)
block/fops.c +45 -13
@@ -725,43 +725,68 @@ static ssize_t blkdev_write_iter(struct kiocb *iocb, struct iov_iter *from)struct file *file = iocb->ki_filp;struct inode *bd_inode =bdev_file_inode (file);struct block_device *bdev =I_BDEV (bd_inode); +dev_t dev = bd_inode->i_rdev;bool atomic = iocb->ki_flags &IOCB_ATOMIC ;loff_t size =bdev_nr_bytes (bdev); +enum hibernate_snapshot_write hibernate_write; +bool hibernate_active; +size_t hibernate_len =0 ;size_t shorted =0 ; +ssize_t hibernate_written =0 ;ssize_t ret;if (bdev_read_only (bdev))return -EPERM ; -if (IS_SWAPFILE (bd_inode) && !is_hibernate_resume_dev (bd_inode->i_rdev)) -return -ETXTBSY ; + hibernate_active =hibernate_snapshot_write_active (dev); +if ((IS_SWAPFILE (bd_inode) && !is_hibernate_resume_dev (dev)) || + hibernate_active) { +if (!is_sync_kiocb (iocb) || !iocb_is_dsync (iocb) || + (iocb->ki_flags &IOCB_DIRECT )) +return -ETXTBSY ; + + hibernate_len =iov_iter_count (from); + hibernate_write =hibernate_snapshot_write_begin (dev, iocb->ki_pos, hibernate_len); +if (hibernate_write ==HIBERNATE_SNAPSHOT_WRITE_NONE ) +return -ETXTBSY ; + }else { + hibernate_write =HIBERNATE_SNAPSHOT_WRITE_NONE ; + } -if (!iov_iter_count (from)) -return 0 ; +if (!iov_iter_count (from)) { + ret =0 ; + goto out_hibernate; + } -if (iocb->ki_pos >= size) -return -ENOSPC ; +if (iocb->ki_pos >= size) { + ret = -ENOSPC ; + goto out_hibernate; + } -if ((iocb->ki_flags & (IOCB_NOWAIT |IOCB_DIRECT )) ==IOCB_NOWAIT ) -return -EOPNOTSUPP ; +if ((iocb->ki_flags & (IOCB_NOWAIT |IOCB_DIRECT )) ==IOCB_NOWAIT ) { + ret = -EOPNOTSUPP ; + goto out_hibernate; + }if (atomic) { ret =generic_atomic_write_valid (iocb, from);if (ret) -return ret; + goto out_hibernate; } size -= iocb->ki_pos;if (iov_iter_count (from) > size) { -if (atomic) -return -EINVAL ; +if (atomic) { + ret = -EINVAL ; + goto out_hibernate; + } shorted =iov_iter_count (from) - size;iov_iter_truncate (from, size); } ret =file_update_time (file);if (ret) -return ret; + goto out_hibernate;if (iocb->ki_flags &IOCB_DIRECT ) { ret =blkdev_direct_write (iocb, from);
@@ -779,9 +804,16 @@ static ssize_t blkdev_write_iter(struct kiocb *iocb, struct iov_iter *from)inode_unlock_shared (bd_inode); } -if (ret >0 ) +if (ret >0 ) { + hibernate_written = ret; ret =generic_write_sync (iocb, ret); + }iov_iter_reexpand (from,iov_iter_count (from) + shorted); + +out_hibernate: +if (hibernate_len) +hibernate_snapshot_write_end (hibernate_write, hibernate_len, + hibernate_written);return ret; }
include/linux/suspend.h +24 -0
@@ -426,10 +426,34 @@ static inline bool pm_hibernation_mode_is_suspend(void) { return false; }int arch_resume_nosmt (void ); +enum hibernate_snapshot_write { +HIBERNATE_SNAPSHOT_WRITE_NONE , +HIBERNATE_SNAPSHOT_WRITE_IMAGE , +HIBERNATE_SNAPSHOT_WRITE_HEADER , +}; +#ifdef CONFIG_HIBERNATION_SNAPSHOT_DEV int is_hibernate_resume_dev (dev_t dev); +bool hibernate_snapshot_write_active (dev_t dev); +enum hibernate_snapshot_write +hibernate_snapshot_write_begin (dev_t dev,loff_t pos,size_t count); +void hibernate_snapshot_write_end (enum hibernate_snapshot_write type, +size_t reserved,ssize_t written);#else static inline int is_hibernate_resume_dev (dev_t dev) {return 0 ; } +static inline bool hibernate_snapshot_write_active (dev_t dev) {return false; } + +static inline enum hibernate_snapshot_write +hibernate_snapshot_write_begin (dev_t dev,loff_t pos,size_t count) +{ +return HIBERNATE_SNAPSHOT_WRITE_NONE ; +} + +static inline void hibernate_snapshot_write_end (enum hibernate_snapshot_write type, +size_t reserved, +ssize_t written) +{ +}#endif /* Hibernation and suspend events */
include/linux/swap.h +9 -0
@@ -377,6 +377,8 @@ extern int find_hibernation_swap_type(dev_t device, sector_t offset);int find_first_swap (dev_t *device);extern unsigned int count_swap_pages (int ,int );extern sector_t swapdev_block (int ,pgoff_t ); +int swapdev_block_to_extent (int type,sector_t block,pgoff_t *offset, +pgoff_t *nr_pages);extern int __swap_count (swp_entry_t entry);extern bool swap_entry_swapped (struct swap_info_struct *si,swp_entry_t entry);extern int swp_swapcount (swp_entry_t entry);
@@ -472,6 +474,13 @@ static inline int add_swap_extent(struct swap_info_struct *sis, {return -EINVAL ; } + +static inline int swapdev_block_to_extent (int type,sector_t block, +pgoff_t *offset, +pgoff_t *nr_pages) +{ +return -EINVAL ; +}#endif /* CONFIG_SWAP */ #ifdef CONFIG_MEMCG void lru_reparent_memcg (struct mem_cgroup *memcg,struct mem_cgroup *parent,int nid);
kernel/power/power.h +1 -0
@@ -170,6 +170,7 @@ extern bool hibernate_acquire(void);extern void hibernate_release (void );extern sector_t alloc_swapdev_block (int swap); +bool swsusp_swap_range_allocated (int swap,loff_t pos,size_t count);extern void free_all_swap_pages (int swap);extern int swsusp_swap_in_use (void );
kernel/power/swap.c +87 -0
93 lines not on this page · raw message
kernel/power/user.c +211 -0
307 lines not on this page · raw message
kernel/power/user.h +11 -0
@@ -5,10 +5,13 @@#include <linux/crypto.h> #include <linux/scatterlist.h> +#include <linux/spinlock.h> #include <linux/suspend_ioctls.h> #include <crypto/aead.h> #include <crypto/aes.h> +struct pid ; +#define SNAPSHOT_ENCRYPTION_KEY_SIZE AES_KEYSIZE_128#define SNAPSHOT_AUTH_TAG_SIZE 16
@@ -23,6 +26,7 @@ struct snapshot_data {bool ready;bool platform_support;bool free_bitmaps; +bool encryption_required;dev_t dev;#if defined(CONFIG_ENCRYPTED_HIBERNATION )
@@ -42,6 +46,13 @@ struct snapshot_data {bool user_key_valid;u64 meta_size;u64 crypt_meta_size; +/* Protect the swap allocation and block-write reservations. */ +spinlock_t crypt_lock; +u64 crypt_swap_allocated; +u64 crypt_swap_reserved; +u64 crypt_header_reserved; +loff_t swap_header_offset; +struct pid *owner_tgid;#endif };
mm/swapfile.c +25 -0
@@ -2379,6 +2379,31 @@ sector_t swapdev_block(int type, pgoff_t offset)return se->start_block + (offset - se->start_page); } +int swapdev_block_to_extent (int type,sector_t block,pgoff_t *offset, +pgoff_t *nr_pages) +{ +struct swap_info_struct *si =swap_type_to_info (type); +struct swap_extent *se; +struct rb_node *rb; + +if (!si || !(si->flags &SWP_WRITEOK )) +return -ENODEV ; + +for (rb =rb_first (&si->swap_extent_root); rb; rb =rb_next (rb)) { + se = rb_entry(rb, struct swap_extent, rb_node); +if (block >= se->start_block && + block - se->start_block < se->nr_pages) { +pgoff_t page = block - se->start_block; + + *offset = se->start_page + page; + *nr_pages = se->nr_pages - page; +return 0 ; + } + } + +return -ENOENT ; +} +/* * Return either the total number of swap pages of given type, or the number * of free pages of that type (depending on @free)
PATCH RESEND v3 3/4 PM: hibernate: permit encrypted snapshot device under lockdown
In reply to Sean RhodesLockdown disables hibernation because restoring attacker-controlled image data can modify kernel memory. Permit opening the userspace snapshot device under lockdown when encrypted hibernation support is built, but require encryption to be enabled before image data can be read or written and before restore or power-off ioctls can proceed.
Tested on StarFighter MTL with lockdown enabled: encrypted uswsusp hibernate and restore used the snapshot device path.
--- kernel/power/hibernate.c | 8 ++++++++ kernel/power/power.h | 1 + kernel/power/user.c | 2 +- 3 files changed, 10 insertions(+), 1 deletion(-)
kernel/power/hibernate.c +8 -0
@@ -114,6 +114,14 @@ bool hibernation_available(void) !secretmem_active () && !cxl_mem_active (); } +bool hibernation_snapshot_dev_available (void ) +{ +return nohibernate ==0 && + (!security_locked_down (LOCKDOWN_HIBERNATION ) || +IS_ENABLED (CONFIG_ENCRYPTED_HIBERNATION )) && + !secretmem_active () && !cxl_mem_active (); +} +/** * hibernation_set_ops - Set the global hibernate operations. * @ops: Hibernation operations to use in subsequent hibernation transitions.
kernel/power/power.h +1 -0
@@ -168,6 +168,7 @@ extern int snapshot_image_loaded(struct snapshot_handle *handle);extern bool hibernate_acquire (void );extern void hibernate_release (void ); +bool hibernation_snapshot_dev_available (void );extern sector_t alloc_swapdev_block (int swap);bool swsusp_swap_range_allocated (int swap,loff_t pos,size_t count);
kernel/power/user.c +1 -1
@@ -184,7 +184,7 @@ static int snapshot_open(struct inode *inode, struct file *filp)unsigned int sleep_flags;int error; -if (!hibernation_available ()) +if (!hibernation_snapshot_dev_available ())return -EPERM ; sleep_flags =lock_system_sleep ();
PATCH RESEND v3 4/4 PM: hibernate: document encrypted snapshot seed ABI
In reply to Sean RhodesDocument the write-only snapshot_seed sysfs file and update the userspace snapshot interface text to describe the opaque wrapped-key flow used by encrypted hibernation.
--- Documentation/ABI/testing/sysfs-power | 18 +++++++++++++ Documentation/power/userland-swsusp.rst | 35 ++++++++++++++++++------- 2 files changed, 44 insertions(+), 9 deletions(-)
Documentation/ABI/testing/sysfs-power +18 -0
@@ -470,3 +470,21 @@ Description: Minimum value: 1 Default value: 3 + +What: /sys/power/snapshot_seed +Date: July 2026 +Contact: [email protected] +Description: + Write-only file present when CONFIG_ENCRYPTED_HIBERNATION=y. + + Trusted early userspace writes a 32-byte seed, encoded as + 64 hexadecimal characters plus an optional newline, before + enabling encrypted userspace hibernation snapshots. + + The first successful write locks the seed until the next boot. + Writing the same seed again succeeds. Writing a different seed + fails with EPERM. + + The kernel does not authenticate the first writer. Trusted early + userspace must provision this file before untrusted privileged + code can run.
Documentation/power/userland-swsusp.rst +26 -9
@@ -116,20 +116,37 @@ SNAPSHOT_S2RAM its state on the basis of the saved suspend image otherwise) SNAPSHOT_ENABLE_ENCRYPTION - Enables encryption of the hibernate image within the kernel. Upon suspend - (ie when the snapshot device was opened for reading), returns a blob - representing the random encryption key the kernel created to encrypt the - hibernate image with. Upon resume (ie when the snapshot device was opened - for writing), receives a blob from usermode containing the key material - previously returned during hibernate. + Enables encryption of the hibernate image within the kernel. Trusted + early userspace must write the 32-byte snapshot encryption seed to + /sys/power/snapshot_seed before calling this ioctl. Upon suspend + (ie when the snapshot device was opened for reading), this ioctl returns + an opaque wrapped key blob and the starting nonce. Upon resume (ie when + the snapshot device was opened for writing), this ioctl receives the + same blob and nonce from usermode after the same seed has been written + to /sys/power/snapshot_seed. The plaintext image key is generated and + unwrapped inside the kernel. + + The first successful seed write establishes the wrapping key for that + boot. The kernel does not authenticate the writer, the TPM policy used to + unseal the seed, or image freshness. Early userspace must provision the + seed before untrusted privileged code can run and must enforce any TPM + policy and rollback protection. + + Under lockdown, direct block-device write() calls to the active swap + backend are restricted to the process which owns the snapshot device and + the extents allocated with SNAPSHOT_ALLOC_SWAP_PAGE. These writes must + use synchronous buffered I/O (O_DSYNC without O_DIRECT), and cannot + exceed the number of pages returned by that ioctl. The swap header may + only be written at the offset supplied with SNAPSHOT_SET_SWAP_AREA. SNAPSHOT_SET_USER_KEY Mixes additional user key material into the data portion of an encrypted hibernate image. The ioctl argument points to struct uswsusp_user_key. key_len must be between 8 and USWSUSP_USER_KEY_SIZE bytes, and reserved - must be zero. The kernel writes meta_size with the encrypted metadata - size that userspace may transfer before providing the user key during - resume. + must be zero. During hibernation the kernel writes meta_size with the + encrypted metadata size. During resume, userspace passes the saved + meta_size back so the kernel can switch keys at the metadata boundary + before the snapshot header has been decrypted. The device's read() operation can be used to transfer the snapshot image from the kernel. It has the following limitations: