AUTHLIB Procedure

Concepts: AUTHLIB Procedure

Metadata-Bound Library

A metadata-bound library is a physical library that is tied to a corresponding metadata secured table object. Each physical table within a metadata-bound library has information in its header that points to a specific metadata object. The pointer creates a security binding between the physical table and the metadata object. The binding ensures that SAS universally enforces metadata-layer access requirements for the physical table—regardless of how a user requests access from SAS. See Overview of Metadata-Bound Libraries.

Using Metadata-Bound Library Passwords

A metadata-bound library contains a single set of passwords that are stored in the secured library object. This set of passwords is added to all data sets that are created in the metadata-bound library. These passwords are not used to authorize user access to the data. They are used to authorize administrator access to repair the binding of physical data to the secured library or table metadata objects. The passwords are also validated in the process of authorizing a user’s access to a data set. They do not determine the permissions that any user is authorized to have.
The metadata-bound library passwords are intended to be known only by the administrators of the metadata-bound library. Knowledge of these passwords is required to restore or re-create secured library and secured table objects in a SAS Metadata Server for data sets in a data library that have lost their previously recorded metadata objects and permissions.
The metadata-bound library passwords also prevent a user from exporting the secured library and secured table objects from a SAS Metadata Server and then importing them to a SAS Metadata Server that an unauthorized user created and controls. This prevents the unauthorized user from using such objects where the user has modified the permissions.
The metadata-bound library passwords are always stored and transmitted in encrypted formats. The encrypted password is not usable to access the data if it is captured from a transmission and presented to SAS as a password value in the SAS language. Administrators might choose to use the PWENCODE procedure to encode the passwords for use in a PROC AUTHLIB statement. Using an encoded password prevents a casual observer from seeing the clear-text password in the PROC AUTHLIB statements that the administrator types.
There are three passwords in the metadata-bound library set that correspond to the READ=, WRITE=, and ALTER= passwords of SAS data sets. For greater simplicity in administration of metadata-bound libraries, it is recommended that you use the PW= option in PROC AUTHLIB statements to specify a single password value. In the context of metadata-bound libraries, the READ=, WRITE=, and ALTER= options do not Create access distinctions. If you are concerned that a single eight character password does not meet your security requirements, then you can choose to set three different password values (using READ=, WRITE=, and ALTER=). Setting different values for these three options can create a 24-character password. However, you must keep track of all password values that you have assigned to a metadata-bound library. You must specify the passwords to do the following:
  • unbind the library
  • modify the passwords
  • repair any inconsistencies in the binding information between what is recorded in the physical files and the actual metadata objects
Tip
All password values must be valid SAS names with a maximum length of 8 characters.
CAUTION:
If you lose the password (or passwords) for a metadata-bound library, then you cannot unbind the library or change its passwords.
Be sure to keep track of passwords that you assign in the CREATE and MODIFY statements.

Setting and Modifying Metadata-Bound Library Passwords

The metadata-bound library passwords are set in the CREATE statement and can be changed with the MODIFY statement. The passwords stored in data sets in the operating system library can be changed by those statements and subordinate TABLES statements. The passwords stored in the data sets can also be changed if the library is unbound from the metadata with a REMOVE statement.
All of the password options in the CREATE, MODIFY, TABLES, and REMOVE statements accept a syntax where two values can be specified separated by a slash (/) (for example, PW=password-value/new-password-value). For CREATE and MODIFY statements, a password value to set in the metadata or data sets is obtained from the password value before the slash (/) if no new password value is specified after the slash (/). The same is true for the REMOVE statement with the additional possibility of specifying the slash (/) and no new password value to indicate that the password should be removed from the data sets during the unbind process. However, note that if the CREATE, MODIFY, or REMOVE statement also specifies TABLESONLY=YES, then any new password values on those statements are ignored.
In general, you do not specify a new password value in a TABLES statement following a CREATE or MODIFY statement. The new value is obtained from the metadata to which the data set is bound or being bound. You can specify a new password value in TABLES statements following a REMOVE statement if you want different data sets to have unique passwords. In that case, you follow these steps:
  1. Change the password for the data sets using a REMOVE statement with TABLESONLY=YES and an individual TABLES statement for each unique password.
  2. Remove the metadata-bound library with a REMOVE statement without TABLESONLY=YES.

Encrypted Data Set Considerations

Some data sets in metadata-bound libraries might be encrypted either with the SAS Proprietary Encryption or Advanced Encryption Standard (AES) algorithm. SAS Proprietary Encryption is specified as ENCRYPT=YES when the data set is created. AES encryption is specified as ENCRYPT=AES and an ENCRYPTKEY= key value when the data set is created. Special considerations apply for these encrypted data sets when processed by the AUTHLIB procedure.
CAUTION:
AES encryption is supported only in SAS 9.4 and later releases.
Do not use AES encryption if the data sets need to be accessible by the second maintenance release of SAS 9.3.
SAS Proprietary Encrypted Data Sets
SAS Proprietary Encryption uses the READ password of the data set as part of the encryption key. Since all metadata-bound data sets in the library share the same set of passwords, it is not necessary to specify the READ password when accessing the file. However, when the READ password is modified on the data set in a CREATE, MODIFY, or REMOVE statement, the data must be re-encrypted with the new password value. This process is done automatically for you in the 9.4 release with a copy-in-place operation. For more information about the copy-in-place operation, see Copy-In-Place Operation.
AES-Encrypted Data Sets
There are two ways to access an AES-encrypted data set:
  • the user must provide the ENCRYPTKEY= key value to open the data set
  • the administrator must have recorded an optional or required encryption key for the metadata-bound library with the ENCRYPTKEY= option in the CREATE or MODIFY statement
Note: The ENCRYPTKEY= value is a passphrase that can be up to 64 characters long from which the actual AES encryption key is later derived, but it is referred to as the encryption key in most SAS documentation.
By recording an optional or required ENCRYPTKEY= key value for the metadata-bound library, the metadata becomes a key store for the encryption key value. Like password values, the key value is always stored and transmitted in encrypted formats. The encrypted key value is not usable to access the data if it is captured from a transmission and presented to SAS as an encryption key value in the SAS language. For more information, see Setting and Modifying Metadata-Bound Library Encryption Options. If there is no recorded encryption key for the library or the data set is encrypted with a different key, then you can specify the encryption key value by specifying the ENCRYPTKEY= option in a TABLES statement. For more information, see TABLES Statement.
Note: If an encryption key is recorded in the metadata with the AUTHLIB procedure, then it is honored by the SAS 9.4 release when creating and replacing SAS data sets, whether the first maintenance release for SAS 9.4 has been applied or not. The SAS 9.4 release of the AUTHLIB procedure cannot be used to administer the metadata-bound library if the REQUIRE_ENCRYPTION=YES attribute has been set.
CAUTION:
Even if you record the encryption key in metadata for the library, you should also record the key elsewhere when using ENCRYPT=AES.
If you lose the metadata and forget the ENCRYPTKEY= key value, then you lose your data. SAS cannot assist you in recovering the ENCRYPTKEY= key value. The following note is written to the log:
NOTE: If you lose or forget the ENCRYPTKEY= value, 
there will be no way  to open the file or 
recover the data.
CAUTION:
If data sets using AES encryption have referential integrity constraints, then the encryption key for all data sets must be available when they are opened for Update access.
Normally, SAS requires that all data sets share the same encryption key. With a recorded optional or required encryption key in metadata, related data sets can have different keys. However, issues can arise if you change the encryption key on one library that has data sets related to data sets in a different library.
Tip
If a metadata-bound library contains AES-encrypted data sets, then SAS recommends that you record an encryption key and use it for all metadata-bound data sets in the library that are encrypted with AES. The best way to ensure that the encryption key is used for all data sets is to require encryption. For more information, see Requiring Encryption for Metadata-Bound Data Sets.

Setting and Modifying Metadata-Bound Library Encryption Options

There are three options that affect metadata-bound library encryption:
  • REQUIRE_ENCRYPTION=
  • ENCRYPT=
  • ENCRYPTKEY=
The metadata-bound library encryption options are set in the CREATE statement and can be changed with the MODIFY statement. The encryption of data sets in the operating system library can be changed by the CREATE and MODIFY statements and subordinate TABLES statements. The encryption of data sets can also be changed if the library is unbound from the metadata by using a REMOVE statement. However, note that if the CREATE, MODIFY, or REMOVE statement also specifies TABLESONLY=YES, then any new encryption options on those statements are ignored. Also note that when encryption options are changed for a data set, the copy-in-place operation is automatically executed to re-encrypt the data with the new options. For more information about the copy-in-place operation, see Copy-In-Place Operation.
The default for the REQUIRE_ENCRYPTION= option is NO when it is used in the CREATE statement. The REQUIRE_ENCRYPTION= option can be changed in the MODIFY statement to YES or NO.
The ENCRYPT= option specifies the encryption type to use: AES, YES, or NO. ENCRYPT=NO is not valid if encryption is required. To record or change a metadata-bound library encryption key, ENCRYPT=AES must be specified. If you want to switch from required encryption with a recorded AES encryption key to required encryption with the SAS Proprietary algorithm, then specify ENCRYPT=YES in the MODIFY statement. This process also removes the recorded encryption key. To remove the recorded encryption key when encryption is not required, specify ENCRYPT=NO in the MODIFY statement. To change the encryption of data sets when unbinding with the REMOVE statement, perform one of the following tasks:
  • specify different encryption options for data sets that are unbound by using TABLESONLY=YES and the encryption options on different TABLES statements
  • change to a common encryption for all data sets that are unbound with the ENCRYPT=option if TABLESONLY is not YES
Similar to password options, the ENCRYPTKEY= option on statements accepts a syntax where two values that are separated by a slash (/) can be specified. Here is an example:
ENCRYPTKEY=key-value/new-key-value
For CREATE and MODIFY statements, the encryption key value to record in the metadata or data sets is obtained from the encryption key value before the slash (/) if
  • ENCRYPT=AES
  • there is no new key value specified after the slash (/)
If you do not specify ENCRYPT=AES, then the encryption key value is used to open data sets but is not recorded in metadata. Unlike password options, you do not remove an encryption key value by specifying a slash (/) after it and leaving it blank. Instead, you use ENCRYPT=YES or ENCRYPT=NO, as discussed in the previous paragraph.
If encryption is required, then you do not specify a new key value in a TABLES statement following a CREATE or MODIFY statement. The new value is obtained from the metadata to which the data set is bound or being bound. If encryption is not required or if you are following a REMOVE statement with TABLESONLY=YES, then you can specify ENCRYPT=AES and a new key value in TABLES statements to have the data set re-encrypted with the new key value.

Retaining and Purging Metadata-Bound Library Credentials

Passwords and encryption keys for a metadata-bound library are collectively referred to as metadata-bound library credentials. Prior to the third maintenance release of SAS 9.4, when any of these credentials were modified, the replaced values were immediately removed from the metadata. Sometimes tables were not processed because another user was accessing the table.
Beginning with the third maintenance release of SAS 9.4, the credentials are retained in metadata and can be used by the system to open data sets that were not modified. This retention enables the user to continue processing tables and the administrator to complete the modification of credentials. The retained credentials are purged if a MODIFY statement that is processing all of the tables in the library determines that all the tables have been successfully changed with the credentials.
An administrator might want to retain the credentials even after all the existing tables have been processed successfully. The following are reasons for retaining the credentials:
  • It enables processing of view files that implemented row and column level security on underlying tables by using the old passwords in the view definition. SAS does not know which view files might contain the passwords and does not have the ability to modify them in the view file. The administrator must redefine the views with the new passwords.
  • It enables processing of data sets restored from backups prior to the modification.
An administrator who wants to retain older credentials and not purge them can specify the PURGE=NO option in the MODIFY statement.
Note: The administrator must specify the PURGE=NO option in each MODIFY statement that processes all tables until the administrator is ready for the replaced credentials to be purged.
If a library contains tables that do not follow our best practices, automatic deletion of old credentials might not occur when issuing a MODIFY statement for all tables. For example, a MODIFY statement that changes the stored encryption key for a library with optional encryption would not modify the keys of data sets whose keys do not match the stored key. Because some data sets were not modified, the old encryption key is not removed. In this case, the PURGE statement must be used to remove the old credentials.
Note: Notes are written to the SAS log whenever a metadata-bound table is accessed and the replaced credentials are used to successfully open the data set. The Note identifies the date and time that these credentials were replaced.
For more information, see PURGE Statement.

Requiring Encryption for Metadata-Bound Data Sets

Beginning in the first maintenance release for SAS 9.4, an administrator can require that all data sets in a metadata-bound library be automatically encrypted when created. This is specified by using the REQUIRE_ENCRYPTION=YES option in the CREATE or MODIFY statements. The type of encryption required depends on whether there is a recorded AES encryption key or not. If there is a recorded encryption key, then all data sets that are bound to the secured library object are automatically AES-encrypted with the recorded encryption key. If there is no recorded AES encryption key, then all data sets are automatically encrypted with the SAS Proprietary algorithm.
In order to automatically encrypt the data sets, a copy-in-place operation is used. For an explanation of the copy-in-place operation, see Copy-In-Place Operation. If the data set is currently encrypted with a different key value, then that key value must be either the current recorded encryption key value or specified with the ENCRYPTKEY= option in the TABLES statement.
Note: If the REQUIRE_ENCRYPTION=YES attribute of a metadata-bound library is set in the metadata with the AUTHLIB procedure, then it is honored by SAS 9.4 when creating and replacing SAS data sets whether the first maintenance release for SAS 9.4 has been applied or not. The pre-maintenance version of the AUTHLIB procedure cannot be used to administer the metadata-bound library if the REQUIRE_ENCRYPTION=YES attribute has been set. The second maintenance release of SAS 9.3 does not honor the REQUIRE_ENCRYPTION=YES attribute, and its AUTHLIB procedure should not be used to administer the library if the REQUIRE_ENCRYPTION=YES attribute is set.

Data Sets in a Metadata-Bound Library That Are Not Bound to Secured Table Objects

It is possible that some data sets in a metadata-bound library do not have the metadata-bound library passwords. These data sets are not considered to be part of the bound library for authorization purposes. This can occur with either of the following scenarios:
  • the data sets existed in the library before it was bound and their passwords differed from the metadata library passwords
  • the data set is AES-encrypted and the encryption key was not available to open the data set in a CREATE or MODIFY statement
See the following examples:
This can also occur if data sets were to be copied into the library by an operating system copy utility.
If a data set was bound before being copied, then the data set is still protected by the permissions that the users have in the secured table object to which it is bound in the original secured library.
If a data set was not bound before being copied, then it is also not bound in the new library or protected by the metadata permissions. If the data set has passwords, then you must supply the appropriate passwords to access the data.
You can use the MODIFY statement to modify the passwords if necessary and to bind the data set to a secured table object in the secured library object to which the library is bound. For more information, see Changing Passwords on Data Sets.