Disk encryption key escrow in IPA

Change Log

 * Jun 3: Added master key storage, and detailed use case descriptions.
 * Jun 8: "Making the packet available" can use the system administrator's identity instead of.
 * Jun 12: Explicitly documented the -related role of.

Escrow packet storage
Stored in. The following information is stored per each packet:

Details:

attributeType ( TBD       NAME 'ipaVolumeEscrowPacket'         DESC 'An encrypted packet containing a secret used for encrypting the volume'        SYNTAX 1.3.6.1.4.1.1466.115.121.1.5   # Binary        SINGLE-VALUE        X-ORIGIN 'IPA v2' )

attributeType ( TBD       NAME 'ipaVolumeHost'        DESC 'Link to the host that contains this volume' SUP memberHost        SYNTAX 1.3.6.1.4.1.1466.115.121.1.12   # DN        X-ORIGIN 'IPA v2' )

attributeType ( TBD       NAME 'ipaVolumeKeySecretType'         DESC 'Type of the secret defined in this packet'        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15   # DirectoryString        SINGLE-VALUE        X-ORIGIN 'IPA v2' ) Defined values: " " and " ", more can be added in the future. This corresponds to * in.

attributeType ( TBD       NAME 'ipaVolumeInfo'         DESC 'Information about a volume: NAME:VALUE'        SYNTAX 1.3.6.1.4.1.1466.115.121.1.40   # OctetString        X-ORIGIN 'IPA v2' ) A multi-valued attribute, stores information about the volume that allows the user to select which escrow packet to use. Each value is a NAME VALUE string, with NAME consisting of characters in. The expected values include the  properties of the volume reported by , e.g.

attributeType ( TBD       NAME 'ipaVolumeKeyObsoletionTimestamp'         DESC 'Time when a key was marked as obsolete'        SYNTAX 1.3.6.1.4.1.1466.115.121.1.24   # GeneralizedTime        SINGLE-VALUE        X-ORIGIN 'IPA v2' )

objectClass ( TBD      NAME 'ipaVolumeKey'        SUP top STRUCTURAL       MUST ( ipaUniqueID $ ipaVolumeHost $ ipaVolumeEscrowPacket )       MAY ( ipaVolumeKeySecretType $ ipaVolumeInfo $ ipaVolumeKeyObsoletionTimestamp )        X-ORIGIN 'IPAv2>' )

Suggested indices:


 * An equality index on, used to find packets related to a single host.  This is sufficient for listing all relevant packets.  It should also be sufficient when searching for a specific packet, there will be at most 10 packets per host in the usual case.
 * A presence index on, used to identify obsolete keys that should be deleted.  Ideally this should be a "b-tree index" (to allow searching for all obsolete packets), but that is not supported by the directory server.

IPA configuration
Additional attributes in :

attributeType ( TBD       NAME 'ipaObsoleteEscrowPacketLifetime'         DESC 'Number of days before an obsolete escrow packet is deleted (if a newer packet for the same volume is available)'        SYNTAX 1.3.6.1.4.1.1466.115.121.1.27   # Integer        SINGLE-VALUE        X-ORIGIN 'IPA v2' )

Escrow packets with  older than   are automatically deleted.

Note: This applies only to packets that were recognized by the IPA server as obsoleted by a newer packet. Obsoleted packets will be recognized by volume UUID (or perhaps other volume attribute that is sufficiently unique), which may not be available for all volume formats. If a volume format does not support reliable recognition of obsolete packets, the IPA server will never automatically mark a packet obsolete, and  will only affect packets that were manually marked obsolete by an administrator.

Todo: Make sure this limitation of automatic packet obsolescence is described in user documentation.

attributeType ( TBD       NAME 'ipaEscrowKeyCertificate'        DESC 'Certificate for encrypting escrow packets'        SYNTAX 1.3.6.1.4.1.1466.115.121.1.5   # Binary        SINGLE-VALUE        X-ORIGIN 'IPA v2' )

The certificate that should currently be used for encrypting escrow packets, in the "PEM" (base64) format. Only one value is permitted.

attributeType ( TBD       NAME 'ipaEscrowKey'        DESC 'PKCS#12-formatted encrypted certificate and private key for encrypting escrow packets'        SYNTAX 1.3.6.1.4.1.1466.115.121.1.5   # Binary        X-ORIGIN 'IPA v2' )

One or more private master keys corresponding to the  values used on this LDAP server. The password used to encrypt the PKCS#12 container may or may not be the same for all private keys.

LDAP user account
An additional account to represent accesses performed by the XMLRPC server (on behalf of a machine identity or of a system administrator) should be added, in a form that allows authenticating to the LDAP server (i.e., probably a Kerberos principal and keytab). This account might be shared with other IPA functions, or exclusive for key escrow. In the rest of this text, the account is called.

Use case handling
(In all cases, the web interface should provide equivalent functionality to the command-line  interface.)

Get master key certificate
Executed by system administrators to retrieve the master key certificate used for encrypting escrow packets. The master key certificate itself, or the process of retreiving the certificate, is becomes a component of the escrow process.

ipa volume_key-current_cert > master.pem
 * The system administrator runs e.g.:
 * The client plugin simply retrieves the current value of the  attribute, and writes it to stdout.  No authentication is necessary.

Send a packet to the server
Executed automatically as a part of IPA enrollment, or manually (by a system administrator, or by a local user). The system administrator's can be e.g. ipa volume_key-store volume [--create-random-passphrase] [--obsolete-older] [escrow_packet...]


 * The client uses  to retrieve volume properties, and if no escrow_packet is specified, it creates an escrow packet (for the "default" secret, usually a data encryption key).  If   is specified, it sets up an additional random passphrase and created an additional escrow packet for it.
 * For each packet (either specified on the command line, or created so far), the client uses XMLRPC with GSSAPI to connect to the IPA server, sending the volume attributes, the packet, and a flag corresponding to the "--obsolete-older" option. It uses either the current Kerberos identity of the user, or the machine identity (FIXME: do we need an option to use the machine identity even if the user has a TGT?).
 * The server checks the identity of the client: if it is an user identity, it uses the Kerberos identity for LDAP authentication. If it is a machine identity, it uses the   Kerberos identity for LDAP authentication.
 * (The server may limit the number of saved packets, perhaps to 100 or 1000 per host, and refuse adding any more (logging the failure).)
 * The server extracts host name from host properties, converts it into a DN for the host. If the client was authenticated with a machine identity, the server verifies the DN matches the authenticated identity.
 * The server creates an ipaVolumeKey LDAP entry.
 * If the "obsolete older" flag was specified, the server searches for other packets for the same host DN that do not have an, and checks if the volume identification for the new packet matches any of the other packets (probably matching mainly on the volume UUID, but the specifics can be dependent on the volume format).  If it finds any matches, it sets the   for the obsoleted timestamps to current date.

List packets
Executed by a system administrator when recovery is necessary, to choose which packet to recover. In an interactive environment (e.g. WWW) the "list packets" and "recover a specific packet" operations can be combined.

ipa volume_key-list [--include-obsolete] hostname
 * The system administrator runs e.g.
 * The client plugin converts hostname into a host DN, and uses it to search for matching  LDAP entries.  The search filter matches the host DN, and, unless   is specified, matches absence of the   attribute.  The client loads all attributes except for.
 * The client lists the packets, sorted by user-readable volume ID (e.g. the " " value of, other volume ID forms can be added later) and by creation time stamp, in that order.  For each packet it shows at least the UUID, volume ID, secret type and creation time stamp.  Options for other output formats and different orderings can be added (at least an option to show all available information would probably make sense).

"Make a packet available" to a system administrator
Executed by a system administrator when a recovery is necessary and a packet was selected, to decrypt it using the master key so that it can be copied to the client machine. In an interactive environment (e.g. WWW) the "list packets" and "recover a specific packet" operations can be combined.

ipa volume_key-get volume_uuid -o packet_file
 * The system administrator runs e.g.
 * where volume_uuid was chosen from results of a previous "list packets" operation.


 * The client plugin asks the user to provide a master key passphrase.
 * The client plugin uses XMLRPC to connect to the server, sending the volume UUID and master key password.
 * Note: The connection must use SSL or a similar mechanism to authenticate the server and to prevent eavesdropping.


 * The server authenticates the user, it should be a "system administrator" permitted to access the key escrow data (FIXME: specifics).
 * The server logs the access.
 * The server connects to the LDAP server using the system administrator's identity, and loads the packet from the  entry specified by the UUID
 * The server connects to the LDAP server as, and loads all encrypted master keys from  .  Each "encrypted master key" is a PKCS#12 container that contains a certificate and a private key.
 * The server forks a separate process (to get a separate NSS context so that the master key is not available after this operation finishes).
 * The child process creates a temporary NSS database, attempts to decrypt each PKCS#12 container using the provided user-provided passphrase (ignoring failures) and load the private key contained in the container. After loading the container, the child process attempts to decrypt the packet, and if successful, sends it back to the parent process.  A prototype implementation of the decryption process is in [[File:Key_management_master_key_unwrapping_prototype.c_gz.bin]].
 * The parent process receives the decrypted packet, waits until the child exits (or kills it), and wipes the temporary NSS database.
 * The parent process sends the decrypted packet back to the client.
 * The client plugin receives the decrypted packet.
 * The client plugin asks the user for a passphrase to protect the packet, encrypts the packet using the passphrase, and writes it to the specified packet_file.

The system administrator copies the packet to the affected machine, and restores access (e.g. storing the packet on a flash drive, booting to rescue mode and using FirstAidKit).

Show secrets contained in a packet
Executed by a system administrator to display a passphrase, to tell it to the user (e.g. over a phone).

ipa volume_key-secrets volume_uuid
 * The system administrator runs e.g.
 * where volume_uuid was chosen from results of a previous "list packets operation".

The operation proceeds exactly like in the above case of '"Make a packet available" to a system administrator', until the client plugin receives the decrypted packet.
 * The client plugin loads the packet and prints the information it contains (including the "secret") to stdout.

Mark a packet as obsolete
Executed by a system administrator to mark a packet as obsolete, e.g. when the automatic obsoletion mechanism can not match the volume correctly.

ipa volume_key-obsolete volume_uuid
 * The system administrator runs e.g.
 * where volume_uuid was chosen from results of a previous "list packets operation". (An alternative invocation form where only a host name is specified might be useful in the case when a computer is decommissioned.)


 * The client plugin locates the  LDAP entry, checks it does not have an   defined yet, and sets it to current time.

Delete a packet
Executed by a system administrator, e.g. when the secrets were stored in error and they need to be immediately deleted to prevent their possible decryption in the future.

ipa volume_key-delete volume_uuid
 * The system administrator runs e.g.
 * where volume_uuid was chosen from results of a previous "list packets operation".


 * The client plugin locates the  LDAP entry and removes it.

Add a master key
Executed by the LDAP server administrator as a part of setting the key escrow system up, or when the previous master key is near its useful lifetime.

ipa master_volume_key-add [--default] pk12file
 * The LDAP server administrator runs e.g.
 * The client plugin prompts for a passphrase, uses it to open the PKCS#12 container and extract the public key certificate.
 * (Optionally the client plugin can verify the private key is a part of the container, or perhaps even recreate the container to ensure a consistent format.)
 * The client plugin adds the PKCS#12 container as a new value of.
 * If  was specified, or if   does not have a value, the client plugin sets   to the public key certificate (replacing the previous value, if any).

Change master key passphrase
Executed by the LDAP server administrator.

ipa master_volume_key-passphrase
 * The ldap server administrator runs e.g.
 * The client plugins prompts for old and new passphrases.
 * The client plugin loads all PKCS#12 containers stored in, attempts to decrypt each container, and if the decryption succeeds, it re-encrypts it using the new passphrase and replaces the old PKCS#12 container with the new one.  Decryption failures are counted and reported, but not considered a failure.

Automatic key expiration
Run on the server from a cron job (probably daily), using a privileged identity.


 * Searches for  LDAP entries with   more than   days.  For each such packet, it checks if a non-obsolete packet entry for the same volume exists (using the same "volume matches" logic that is used for automatic obsoletion).  If a non-obsolete packet exists, the obsolete packet entry is removed.

Questions

 * What ACIs protect the various LDAP entries and attribues? What other access controls are enforced by IPA (apart from the necessity to known the master key passphrase?)  Perhaps a   group?
 * Suggested rules:
 * Anyone can access the public master key certificate in.
 * access restrictions are analogous to the restriction on machine account entries, except for the  attribute.
 * The  attribute is accessible by   and a group of system administrators allowed to handle escrow packets (e.g. the above-suggested   group).
 * can be read by, read and modified by users with highest level of trust (LDAP server administrators)..


 * Can the software deployed on client machines to perform the "send a packet to the server" operation be in Python? I was once told it should not, although the current software to enroll a client is in Python.