alter encryption key

Description

Changes the current password for an encryption key.

For more information about encrypted columns, see the Encrypted Column Users Guide.

Syntax

alter encryption key [[database.][owner].] keyname
	{ [ as | not default ]
		| [ with passwd 
			'password' | system_encr_passwd | login_passwd ]
			modify encryption 
			 [ with passwd 
			'passwd' | system_encr_passwd | login_passwd ]
		| with passwd 'password'
			add encryption [ with passwd 'password' ] 
			for user user_name
			[ for login_association | for recovery ]
		| drop encryption for
			{ user user_name | recovery } 
		| [ with passwd 'password ']
			recover encryption with passwd 'password'
		| modify owner user_name
}

Parameters

keyname: is the name for a column encryption key.

as [not] default: indicates that the database default property should be assigned to, or unassigned from, this key.

with passwd ['password' | system_encr_passwd | login_password ]: specifies the current password Adaptive Server uses to decrypt the column encryption key, and a new password for one of the following purposes:

Modify the encryption of a key or a key copy.

Encrypt a newly-added key copy. The key owner can add key copies for individual users that are accessible through a private password or a login password.

Recover the encryption key after losing a password

Adaptive Server supports the following kinds of passwords for keys:

password – a character string up to 255 bytes long.

login_passwd – tells Adaptive Server to use the session’s login password.

system_encr_passwd – is the system encryption password for the current database.

If you do not specify with passwd, the default is system_encr_passwd.

modify encryption: indicates you are modifying the encryption key or key copy.

add encryption: adds encrypted key copy for a designated user.

for user user_name: specifies the user for whom you are adding or dropping a key copy.

for login_association: indicates that the key copy being added will later be encrypted by the assigned user’s login password during his or her first access to this key.

for recovery: indicates this key copy is for recovery purposes.

drop encryption: indicates that you are dropping the key copy for the specified user.

recover encryption: makes the base key accessible through a new password. Does not apply to key copies.

modify owner: changes the key’s owner to the specified user.

Examples

Example 1

Changes my_key to the default encryption key:

alter encryption key my_key as default

You must have the sso_role or keycustodian_role to change the default property of a key. If the command above is executed by:

The system security officer, Adaptive Server removes the default property unconditionally from the previous default key, if one exists.
The key custodian, he or she must own my_key. The key custodian must own the previous default key, if one exists.

To remove the default property from my_key, the SSO or the key custodian as owner of the key, executes:

alter encryption key my_key as not default

If my_key is not the default key, this command returns an error.

Example 2

Changes the password on the important_key encryption key:

alter encryption key important_key 
     with passwd 'oldpassword'
     modify encryption 
     with passwd 'newpassword'

If this command is executed by:

The key owner – the command re-encrypts the base key
The user assigned a key copy – the command re-encrypts that key copy.

Example 3

Changes the password on a key copy to the current session’s login password (can be executed only by a user who has been assigned a key copy):

alter encryption key important_key
     modify encryption
     with passwd login_passwd

You can encrypt only key copies with a login password. Adaptive Server returns an error if you attempt to encrypt the base key with a login password.

Example 4

Changes the password for the important_key encryption key to the system password:

alter encryption key important_key
     with passwd 'ReallyBigSecret'
     modify encryption with passwd system_encr_passwd

This command can be executed only by the key owner or a user with sso_role, and is allowed only if a key has no key copies. (Base keys with copies must be encrypted by a user-specified password.) This example modifies the encryption of the base key.

Example 5

Changes the password for the important_key encryption key from the system encryption password to a new password. Because the system encryption password is the default password, it need not be specified in the statement:

alter encryption key important_key
     modify encryption
     with passwd 'ReallyNewPassword'

Example 6

Adds encryption for user “ted” for the important_key encryption key with the password just4now:

alter encryption key important_key
     with passwd 'TopSecret' 
     add encryption with passwd 'just4now'
     for user 'ted'

You must be a key owner or a user with the sso_role to execute this command. Adaptive Server uses the password “TopSecret” to decrypt the base key, making a copy of the raw key and encrypting it for user “ted” using the password “just4now.”

Example 7

Modifies the encryption for user “ted” to use a new password. Only “ted” can execute this command:

alter encryption key important_key
     with passwd 'just4now'
     modify encryption
     with passwd 'TedsOwnPassword'

Example 8

Drops encryption for user “ted” for the important_key encryption key (you must have the sso_role or be the key owner to execute this command):

alter encryption key important_key
     drop encryption for user 'ted'

Example 9

Modifies the owner of important_key to new owner, “tinnap” (you must have the sso_role or be the key owner to execute this command):

alter encryption key important_key modify owner tinnap

Example 10

Set up the recovery key copy and uses it for key recovery after losing a password:

The key custodian originally creates a new encryption key protected by a password.
```
create encryption key key1 for AES passwd 'loseitl8ter'
```

The key custodian adds a special encryption key recovery copy for key1 for user “charlie.”

alter encryption key key1 with passwd 'loseitl8ter'
     add encryption
     with passwd 'temppasswd'
     for user charlie
     for recovery

“charlie” assigns a different password to the recovery copy and saves this password in a locked drawer:

alter encryption key key1
     with passwd 'temppasswd'
     modify encryption
     with passwd 'finditl8ter'
     for recovery

If the key custodian loses the password for base key, he can obtain the password from “charlie” and recover the base key from the recovery copy of the key using:
```
alter encryption key key1
     with passwd 'finditl8ter'
     recover encryption
     with passwd 'newpasswd'
```

Usage

If the SSO issues alter encryption key to set the key as the database default, the specified key replaces any existing key as the default.
If the key custodian issues alter encryption key to set a key as the database default, the specified key and the current default key (if it exists) must be owned by the key custodian.
Keys are owned and managed by users with keycustodian_role, the sso_role, or by users who are explicitly granted permission for the create encryption key command. Keys are used by all users who have permissions to process and see the data from encrypted columns. How Adaptive Server protects keys affects how they are accessed:
1. The key owner creates the key for encryption by the system encryption password – When users access the encrypted data, Adaptive Server decrypts the base key using the system encryption password. The key owner does not create individual key copies for users.
2. The key custodian encrypts the base key with an explicit password – Rather than create key copies, the key custodian shares this password with all users who process encrypted data. Users or applications must supply this password with the set encryption passwd command to access data. See set encryption passwrd.
3. The key custodian adds key copies for end users so that users do not have to share passwords. Users must enter their key copy’s password using set encryption passwd to access encrypted columns. Alternatively, the key custodian can set up key copies for encryption by the key assignee's login password. This password does not have to be entered through set encryption passwd
When you create a key using create encryption key, Adaptive Server saves the key in encrypted form, along with the key’s properties, as a row in sysencryptkeys. This row represents the base key. The key owner can choose to allow access to encrypted data exclusively through the base key, or use alter encryption key to add key copies for individual users.
If you do not include the with passwd parameter with alter encryption, Adaptive Server uses the system encryption password.
You cannot use the system encryption password to alter the base key of a key that has copies, and you cannot encrypt copies of keys with the system encryption password.
Users assigned key copies modify only their own key copies.
If you specify for login_association, Adaptive Server temporarily encrypts the key copy with the system encryption password. The key copy is reencrypted by the copy owner’s login password when he or she encrypts or decrypts data with that key.
You cannot specify for recovery and login_association for the same key copy.

Permissions

You must be:

The system security officer or a user with the keycustodian_role to execute alter encryption key as default or not default. This permission cannot be granted to other users
The system security officer or the key owner to use alter encryption key to add or drop key copies, recover the key, and modify the key owner.
The system security officer or the key owner to execute alter encryption key to modify the password of the base key. You must be the user assigned the key copy to modify the key copy password. You implicitly have permission to modify your own key copy’s password.

Auditing

For information about auditing encrypted columns, see Chapter 6, “Auditing Encrypted Columns,” in the Encrypted Columns Users Guide.