Fedora

Disk encryption key escrow in IPA

From FedoraProject

Contents 1 Change Log 2 Data in LDAP 2.1 Escrow packet storage 2.2 IPA configuration 2.3 LDAP user account 3 Use case handling 3.1 Get master key certificate 3.2 Send a packet to the server 3.3 List packets 3.4 "Make a packet available" to a system administrator 3.5 Show secrets contained in a packet 3.6 Mark a packet as obsolete 3.7 Delete a packet 3.8 Add a master key 3.9 Change master key passphrase 3.10 Automatic key expiration 4 Questions

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 ipaXMLRPCServiceAccount.
• Jun 12: Explicitly documented the ipaEscrowKey-related role of ipaXMLRPCServiceAccount.

Data in LDAP

Escrow packet storage

Stored in ipaUniqueID=..., cn=volume_keys, dc=.... The following information is stored per each packet:

Attribute	Meaning and use	Comment
Packet ID	ipaUniqueID used in the DN	dm-crypt volumes do not carry any identifier for distinguishing even between two volumes on a host
Escrow packet	A blob containing the encrypted "secret"	Size probably 1000–1500 bytes
Host reference	Host this packet applies to
"Secret" type	Purpose of the packet: data encryption key / passphrase / other
Volume identification	Multi-valued: properties of the volume that can be used to identify the correct packet
Packet filing time	Time when this packet was sent to the server	Provided by the directory server automatically in creationTimestamp
Obsoletion time	If this packet stores an obsolete secret, time when the server was notified about it	Used for automatic deletion of old secrets

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: "data encryption key" and "passphrase", more can be added in the future. This corresponds to LIBVK_SECRET_* in libvolume_key.h.

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 [a-zA-z0-9_/]. The expected values include the LIBVKP_VP_IDENTIFICATION properties of the volume reported by libvk_volume_dump_properties, e.g.

Name	Value
hostname	Host name, as known on the computer
volume_format	Volume format, corresponds to LIBVK_VOLUME_FORMAT_* in libvolume_key.h
volume_uuid	Volume UUID, using a volume format-specific syntax
volume_label	Volume label
volume_path	Path to a block special file representing the device on the specified host. The path is not necessarily "canonical". There might be more than one attribute value with this NAME.
luks/passphrase_slot	An integer identifying the LUKS slot a passphrase is valid for

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 ipaVolumeHost, 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 ipaVolumeKeyObsoletionTimestamp, 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 ipaConfig:

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 ipaVolumeKeyObsoletionTimestamp older than ipaObsoleteEscrowPacketLifetime 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 ipaObsoleteEscrowPacketLifetime 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 ipaEscrowKeyCertificate 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 ipaXMLRPCServiceAccount.

Use case handling

(In all cases, the web interface should provide equivalent functionality to the command-line ipa 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.

• The system administrator runs e.g.:

ipa volume_key-current_cert > master.pem

• The client plugin simply retrieves the current value of the ipaEscrowKeyCertificate 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 libvolume_key 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 --create-random-passphrase 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 ipaXMLRPCServiceAccount 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 ipaVolumeKeyObsoletionTimestamp, 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 ipaVolumeKeyObsoletionTimestamp 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.

• The system administrator runs e.g.

ipa volume_key-list [--include-obsolete] hostname

• The client plugin converts hostname into a host DN, and uses it to search for matching ipaVolumeKey LDAP entries. The search filter matches the host DN, and, unless --include-obsolete is specified, matches absence of the ipaVolumeKeyObsoletionTimestamp attribute. The client loads all attributes except for ipaVolumeEscrowPacket.
• The client lists the packets, sorted by user-readable volume ID (e.g. the "volume_path" value of ipaVolumeInfo, 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.

• The system administrator runs e.g.

ipa volume_key-get volume_uuid -o packet_file

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 ipaVolumeKey entry specified by the UUID
• The server connects to the LDAP server as ipaXMLRPCServiceAccount, and loads all encrypted master keys from ipaEscrowKey. 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).

• The system administrator runs e.g.

ipa volume_key-secrets volume_uuid

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.

• The system administrator runs e.g.

ipa volume_key-obsolete volume_uuid

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 ipaVolumeKey LDAP entry, checks it does not have an ipaVolumeKeyObsoletionTimestamp 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.

• The system administrator runs e.g.

ipa volume_key-delete volume_uuid

where volume_uuid was chosen from results of a previous "list packets operation".

• The client plugin locates the ipaVolumeKey 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.

• The LDAP server administrator runs e.g.

ipa master_volume_key-add [--default] pk12file

• 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 ipaEscrowKey.
• If --default was specified, or if ipaEscrowKey does not have a value, the client plugin sets ipaEscrowKeyCertificate to the public key certificate (replacing the previous value, if any).

Change master key passphrase

Executed by the LDAP server administrator.

• The ldap server administrator runs e.g.

ipa master_volume_key-passphrase

• The client plugins prompts for old and new passphrases.
• The client plugin loads all PKCS#12 containers stored in ipaEscrowKey, 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 ipaVolumeKey LDAP entries with ipaVolumeKeyObsoletionTimestamp more than ipaObsoleteEscrowPacketLifetime 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 cn=decryptescrowpacket,cn=taskgroups,cn=accounts,dc=... group?

  Suggested rules:

  • Anyone can access the public master key certificate in ipaEscrowKeyCertificate.
  • ipaVolumeKey access restrictions are analogous to the restriction on machine account entries, except for the ipaVolumeEscrowPacket attribute.
  • The ipaVolumeEscrowPacket attribute is accessible by ipaXMLRPCServiceAccount and a group of system administrators allowed to handle escrow packets (e.g. the above-suggested decryptescrowpacket group).
  • ipaEscrowKey can be read by ipaXMLRPCServiceAccount, 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.

Copyright © 2012 Red Hat, Inc. and others. All Rights Reserved. For comments or queries, please contact us.

The Fedora Project is maintained and driven by the community and sponsored by Red Hat. This is a community maintained site. Red Hat is not responsible for content.

• This page was last modified on 12 June 2009, at 17:36.
• Content is available under Attribution-Share Alike 3.0 Unported.

• Privacy policy
• About FedoraProject
• Disclaimers
• Sponsors
• Legal
• Trademark Guidelines