efskeymgr Command

Purpose

Manages user and group repositories for the Encrypted File System (EFS) keys (or keystores).

Syntax

efskeymgr -?

efskeymgr -q

efskeymgr -V

efskeymgr [-L load_module]-C <group>

efskeymgr -P < Open-SSH Public Key file >

Note: The public key file is located in the ~/.ssh/ directory directory.

efskeymgr [-L load_module] [ -d ] [ -k <ks> ] [ -g ] [ -p <pw> ] -v

efskeymgr [-L load_module] [ -d ] [ -k <ks> ] -m

efskeymgr [-L load_module] [ -d ] [ -k <ks> ] [ -g ] [ -p <pw> ] -o <cmd>

efskeymgr [-L load_module] [ -d ] [ -c <cmd> ]

efskeymgr [-L load_module] [ -d ] [ -k <ks> ] [ -g ] [ -p <pw> ] -n

efskeymgr [-L load_module] [ -d ] [ -k <ks> ] [ -g ] [ -p <pw> ] -r <mode>

efskeymgr [-L load_module] [ -d ] [ -k <ks> ] [ -g ] [ -p <pw> ] -s <ks2>

efskeymgr [-L load_module] [ -d ] [ -k <ks> ] [ -g ] [ -p <pw> ] -S <ks2>

efskeymgr[-L load_module] [ -d ] [ -k <ks> ] [ -g ] [ -p <pw> ] -R <algo>

efskeymgr [-L load_module] [ -d ] [ -k <ks> ] [ -g ] [ -p <pw> ] -D <fp>

efskeymgr [-L load_module] [ -d ] [ -k <ks> ] [ -g ] [ -p <pw> ] -e <file>

Description

The efskeymgr command is dedicated to all key management operations needed by an EFS. Once an EFS is enabled on the system with the efsenable command, the keystores (public and private key repositories) are created in the /var/efs directory.

The initial password of a user keystore is the user login password. Group keystores and admin keystores are not protected by a password but by an access key. Access keys are stored inside all user keystores that belong to this group.

When you open a keystore (at login or explicitly with the efskeymgr command), the private keys contained in this keystore are pushed to the kernel and associated with the process. If access keys are found in the keystore, the corresponding keystores are also opened and the keys are automatically pushed into their kernel.

Keystores support two administration modes: admin mode and guard mode.

admin mode: When a keystore is set to this mode, an EFS administrator with the aix.security.efs RBAC authorization and the access key to admin keystore can open the keystore for management including password reset, key regeneration, access key addition or removal, and so on.
guard mode: When a keystore is set to this mode, the EFS administrator cannot get access to the keystore. In this mode, if the password to keystore is lost, there is no possible recovery of the private key.

When the keystore password is the same as the login password, the keystore is automatically opened at the login time and the keys are available in the session. The keystore password is kept in sync with the login password when the passwd command is used and the old password is provided. If at some point the keystore password is not in sync with the login password, you can change the keystore password using the efskeymgr command. When the passwords are not synchronized, the keys are no longer automatically associated with the session when you log in.

The following command grants or removes the EFS credentials only for the execution of the cmd command. When the cmd command returns, the previous process credentials are restored.

efskeymgr –o <cmd> and efskeymgr –c <cmd>

When a private key is regenerated in a keystore, a new private key is created and the old key is marked "deprecated".

Note: The new key is not pushed into the kernel. You must open your keystore again, either with the efskeymgr command or by closing and opening your session, for the new key to be available for file operations.

The deprecated key can still be used to decrypt files, but is no longer used to encrypt files. The deprecated key can be removed from the keystore, but in this case all files that were encrypted with the old key will no longer be accessible.

Note: This EFS command requires that Role Based Access Control (RBAC) is enabled on the system, which is the default setting.

Delayed operations

In some cases, the keystore cannot be modified directly by a command or an action. When this occurs, a special file is created in the keystore directory, and will be parsed next time the keystore is opened. This special file is called a cookie. For keystores in admin mode, the cookies are parsed automatically when the keystore is opened (at login or when the efskeymgr command is run). For keystores in guard mode, the cookies are never automatically parsed. The user must give its approval for each modification of its keystore. When you open a session, a message is displayed if one or more operations are pending on your EFS keystore:

Your private key must be regenerated.
You are granted access to group/group1 keystore.

You must run the efskeymgr -v command to process pending operations.

The following actions are possible:

Private key regeneration. This results in a new private key being generated, and the old one being marked "deprecated".
New access key. When you accept this cookie, you obtain access to a new keystore (for example, keystore of a group to which you are added).
Remove access key. When you accept this cookie (for example, when the access key is removed from a group), you loose your access to a keystore.

Note: When you run the efskeymgr command with any flag that opens your keystore, for example, the -v flag, you are prompted what you want to do with each cookie. The choices are as follows:

Accept the cookie: your keystore is modified according to the cookie, then the cookie is destroyed.
Postpone the cookie: your keystore is not modified and the cookie is not removed. You will be prompted next time for action.
Delete the cookie: your keystore is not modified and the cookie is removed. You must use the efskeymgr command to do the action again.

Flags

Item	Description
General flags:
-d	Verbose mode.
-g	Does not process pending operations when opening the keystore.
-k ks	The operation is targeted to the ks keystore instead of the active user’s keystore. The ks value can be as follows: user/<login> User <login> keystore. group/<grpname> Group <grpname> keystore. admin/ EFS administration keystore.
-L load_module	Specifies the loadable module to use for keystore operations.
-p pw	Password to use to open the keystore. It is not advised to use this flag as it can be seen by other users using the ps command, for example.
-P filename	Push the public key cookies for all the keys present in the OpenSSH file located in the ~/.ssh/authorized_keys directory.
Flags for commands (no access to the keystore files):
-?	Displays the command help and exits.
-q	Displays a list of supported algorithms for the key regeneration.
-V	Displays the keys associated with the active process credentials in the kernel.
Flags for commands (read-only access to keystores):
-c <cmd>	Removes all keys from the kernel, then runs the cmd command. The keys are restored when the cmd command terminates.
-m	Lists all pending operations on the keystore.
-o <cmd>	Opens the keystore and pushes the keys, then runs the cmd command. The keys are discarded when the cmd command terminates.
-v	Displays the content of the keystore file.
Flags for commands (read/write access to keystores):
-C <group>	Creates the keystore of the group group.
-D <fp>	Removes a deprecated private key from the keystore. The fp value is the key fingerprint.
-e <file>	Exports a keystore to a file. The file is PKCS#12 encoded and contains the public and private keys from the keystore. This file can be used in openssh, for example.
-n	For user keystores, prompts for a new password for the keystore. For group keystores, generates a new access key and sends to group members. For admin keystores, generates a new access key. The key must then be sent to the EFS administrators with the efskeymgr command.
-R <algo>	Regenerates the keystore private key. See the -q flag for the valid values for the algo parameter.
-r <mode>	Changes the keystore administration mode. The mode value can be as follows: admin The EFS administrator can administer the keystore. Pending operations are applied automatically. guard The EFS administrator cannot manage the keystore. The user is prompted for any pending operation.
-S <ks2>	Removes the ks2 access key from the keystore. On subsequent opening of keystore, the ks2 private key is no longer pushed automatically.
-s <ks2>	Sends the keystore access key to the ks2 keystore. On subsequent opening of the ks2 key, the keystore private key is loaded automatically.

Exit status

Item	Description
0	The command ran successfully.
1	An error occurred during the execution of the command.
2	A syntax error occurred on the command line.

Security

Attention RBAC users and Trusted AIX users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in AIX® Version 7.1 Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

To view your keystore content, enter:
```
efskeymgr –v
```
To view the keys associated with the active shell, enter:
```
efskeymgr -V
```
To regenerate the private key from your keystore, enter:
```
efskeymgr –R RSA_1024
```

To delete a deprecated key, enter:

efskeymgr –D dbb62547:d6925088:45357fd3:54cddbba:27b255a9

To send the access key of the group "students" to the user "joe", enter:
```
efskeymgr –k group/students –s user/joe
```
To push the Open-SSH Client users Open-SSH Public key cookies in the target keystore, where the ~/.ssh/authorized_keys file contains the installed public keys, enter:
```
efskeymgr  -P  ~/.ssh/authorized_keys
```
To create Group keystore directly on LDAP, if configured:
```
efskeymgr -L LDAP -C staff
```

Files

Item	Description
/var/efs	Contains all keystores.
/etc/security/user	Contains the EFS attributes for the creation and management of users keystore.
/etc/security/group	Contains the EFS attributes for the creation of groups keystore.