marry(ADM)


marry -- bind block device to a regular file

Syntax

/usr/sbin/marry -a [-b blocks] [-c passphrase] [-s] regfile ...

/usr/sbin/marry -d regfile | marrydev ...

/usr/sbin/marry -l

Description

The marry command associates a block special device file and a character special device file with regfile. regfile may then be accessed as a block device using the special device file. This allows operations such as mounting, which normally can only be performed on a block special device file, to be performed on a regular file.

It enables you to create a filesystem within regfile using mkfs(ADM) on the associated block device file. The regfile is thus the filesystem's backing store. You can then check its integrity with fsck(ADM), and mount and unmount it using mount(ADM) and umount(ADM).

It optionally allows you to automatically encrypt and decrypt data stored in regfile. This provides the ability of any underlying image (a filesystem, cpio, tar, etc. for example) to be protected by encryption.

A maximum of 255 concurrent marriages are allowed by default.

Only a user with appropriate privileges can use the marry command.

Command options


-a
Associate a device interface with the regular file regfile, and create a block special device file /dev/marry/regfile and and a character special device file /dev/marry/rregfile through which it can be accessed. If a different block or character device pathname is required, a link should be created to the node in the /dev/marry directory hierarchy.

The following points on pathname resolution and marry special device permissions and ownership apply to the character special device file as well.

If regfile is a relative pathname, marry creates a block device file with the path /dev/marry/currdir/regfile where currdir is the current working directory.

If regfile has symbolic links, marry resolves them and creates the a block device file with the path /dev/marry/resolvedpath/regfile

marry gives the block device file and any intermediate directories the same read and search permissions, owner, and group as the regular file and its intermediate directories. marry removes write permission from the block device file and any intermediate directories.


-b blocks
Specify, in number of 512 byte blocks, the maximum size of the married device. By default, blocks is the size of regfile when married. Use this option when marrying an empty file prior to running mkfs.

-c passphrase
The contents of regfile is encrypted. The operation of encrypting/decrypting regfile is performed via accessing its associated marry block and character special device file. The passphrase is used to generate the keys that encrypt/decrypt regfile. A passphrase is similar to a password but longer. It typically is a nonsensical sentence or phrase. Details of the encryption feature is provided in the ``Encryption'' section below.

-d
Delete the block and character special device files (/dev/marry/regfile and /dev/marry/rregfile) and dissociate the device interface from the regular file regfile. The pathname given may also be that of the married device file.

A marriage may be deleted while the married device is in use; the marriage will remain in force until the device is closed. It is good practice, however, to close the device before deleting the marriage.


-l
List current marriages in the form:

/regfile by owner to major,minor /dev/marry/regfile status

If a regular file cannot be found, marry displays from instead of to.

If the block special device file cannot be found, marry displays removed instead of /dev/marry/regfile.

The status field shows whether the device is currently open, closed, or is to be unmarried on close. (Unmarry-on-close is displayed for marriages where marry -d regfile was executed on an open device file.)


-s
I/O to regfile, via its associated block or character special device files, is synchronized to regfile's backing store on every access. This may be the desired if regfile is being used as the backing store of a writeable filesystem and integrity is critical. The cost of using this option is performance. With out using this option the default functionality is to synchronize regfile when it is closed (i.e. when regfile is disassociated from the marry device interface via the -d option) or when it is periodically synchronized via the operating system's file synchronization mechanism (as are all files).

Encryption

The Marry Encrypting/Decrypting Feature is enabled with the -c passphrase option. The only supported, and thus default, cipher algorithm is the 128 bit Advanced Encryption Standard (AES) algorithm (aka the Rijndael block cipher).

The physical layout of an encrypted regfile differ from a regfile that is not encrypted via the Marry encryption feature. An encrypted regfile is divided into two consecutive and non-overlapping areas.

Encrypted State Information User Data

 +----------------------------+-----------+
 |Encrypted State Information | User Data |
 +----------------------------+-----------+

The Encrypted State Information Area consists of the first five blocks of regfile. It contains state information used by the Marry driver to manage an encrypted regfile. This Area is not accessible from regfile's associated block and character special device files. The User Data Area is the area in regfile accessible from its associated block and character special device files. The file offset of zero starts a the beginning of the User Data Area. NOTE: The five blocks of Encrypted State Information in regfile needs to be accounted for when allocating space for regfile.

The first time encryption is enabled on a regfile that was not previously encrypted via the Marry Encryption Feature, the Encrypted State Information Area is generated and written out to regfile. The second and subsequent times encryption is enabled on regfile the passphrase is validated and the Encrypted State Information Area is authenticated. If either the passphrase validation or Encrypted State Information Area authentication fail, the marriage does not succeed. If the validation and authentication succeed, the marriage is created and access to the User Data Area is made available via the associated block and character special device files.

WARNING: Do not attempt to enable the Marry encryption Feature for the first time on a regfile containing data since its first five blocks will be overwritten with the Encrypted State Information Area. Enabling Marry encryption feature for the first time should only be done on an empty or new regfile.

The passphrase, used to generate the keys that are used to encrypt/decrypt regfile, is a minimum of 16 characters and a maximum of 64 characters. It has been estimated that each character provides about 2 bits of entropy (i.e, randomness). Hence with a 64 character passphrase one can achieve approximately 128 bit keys. The Marry encryption feature provides another mechanism, called Stretching, that increases the passphrase's entropy. This mechanism is tuneable; it is described in marry(HW) with the /etc/conf/pack.d/marry/space.c file.

Special attention to regfile's ownership and permission is needed since regfile's contents are decrypted, via reading its associated block or character special device files. This also includes any other means of access to the associated block or character special device files such as a filesystem's mount point for example.

Examples

The following example shows marry being used to list current marriages. Of the three married files listed, the first is a diskette image that is mounted as a filesystem; the second is a file being used to create a filesystem, and the third shows a marriage that will be unmarried when the device is closed.
   #marry -l
   /hba.image by root to 15,1 /dev/marry/hba.image 2880 blocks open
   /tmp/a by root to 15,2 /dev/marry/tmp/a 5000 blocks open
   /tmp/c by sachin to 15,3 /dev/marry/tmp/c 3000 blocks unmarry-on-close

The following example shows marry being used to setup an encrypted regfile to be used as a backing store for a filesystem. Note the extra five blocks allocated for the Encrypted State Information Area.

   # chown root backingstore mountpoint
   # chgrp appgrp backingstore mountpoint
   # chmod 660 backingstore
   # chmod 750 mountpoint
   # marry -a -b 10005 -c "The PassPhrase" backingstore
   # mkfs -F vxfs /dev/marry/rbackingstore 10000
   # mount /dev/marry/backingstore /mountpoint

Limitations

marry requires the existence of the dev/rmarry node, and the marry(HW) driver to be configured into the kernel.

fdisk(ADM) cannot be applied to a married device.

A regular file may be extended by writing to the married device; the final block is padded with null characters.

Only a regular file may be married; a directory cannot be married.

A file on a married mounted filesystem cannot be married.

A married file should not be executed or opened for writing while the device is open.

A filesystem containing a married file cannot be unmounted while the associated device is open. If the device is not open, unmounting a filesystem containing married files automatically dissolves their marriages.

Sparse Reading an encrypted (via the marry encryption feature) regfile's associated block and character special device files directly does not work properly. A Sparse Read is a short cut used when accessing holes in a file. The Sparse Read returns zero filed data without accessing the file's backing store. A hole is created by seeking past the End of File (EOF) and writing data. The hole is between the previous EOF and the start of data that was written beyond the previous EOF. There can be more than one hole in a file.

marry can not distinguish between data returned from a Sparse Read or from regfile's backing store and will incorrectly decrypt Sparse Read data. This is only relevant when accessing regfile's associated block and character special device files directly. It is not an issue, for example, when the associated special device files are being accessed accessed via filesystem interface. In this case regfile is the backing store for the filesystem mounted on its associated special device file.

A Sparse Read to a file in the filesystem using regfile as its backing store handles the read request at the filesystem level and never issues an I/O to its backing store (which is regfile). NOTE: regfile itself is a file and has a backing store which is associated with the filesystem regfile resides. This is not to be confused with regfile being the backing store for a marry special device file. Work Around: If I/O access directly to regfile's associated block and character special device files is random, and thus subject to creating holes the following work arounds can be done. Essentially regfile is initialized to either all encrypted zeros or encrypted random data before it is accessed.

   # marry -a -c "PassPhrase" backingstore
   # dd if=/dev/zero of=/dev/marry/rbackingstore count=size
   or
   # dd if=/dev/random of=/dev/marry/rbackingstore count=size

Files


/dev/rmarry
permanent character device file used to control the marriage driver

/dev/marry/regfile
block device file temporarily associated with the regular file pathname regfile

/dev/marry/rregfile
character device file temporarily associated with the regular file pathname regfile

References

fsck(ADM), marry(HW), mkfs(ADM), mount(ADM), umount(ADM)
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 02 June 2005