Understanding sctool

Centrify provides a group policy, Enable smart card support, to enable smart card support on Mac computers. This group policy uses the sctool utility to add smart card specific strings to the authorization database and to create the /etc/cacloginconfig.plist file. In general, you can use the group policy to enable smart card support. However, the sctool utility is also available to specifically configure or diagnose smart card support on any Mac computer.

When you disable smart card support, with the group policy or with sctool, the smart card strings are removed from the authorization database and /etc/cacloginconfig.plist is deleted.

See Configuring a Mac computer for smart card login for detailed information about using group policies to enable smart card login and screen locking.

Note:   When you enable or disable smart card support with sctool, the change is temporary, unless the group policy, Enable smart card support, is not configured. For example, if the policy is set to enable smart card support, and you disable it with sctool, at the next reboot the policy takes effect and smart card support is re-enabled. If the policy is not configured, you can control smart card support on individual computers using sctool.

Synopsis

sctool  -e --enable
        -d --disable
        -s --status
        -u --update-upn-map [mapping]
        -D --dump
        -S --support
        -c --clearcrls
        -r --revokecheck
          Extra options for -r:
            -t --type [ocsp|crl]:[none|best|cert|all]
            -p --priority [ocsp|crl|both]
            -l --localocsp [ocsp server url]
        -k --pkinit userPrincipalName
        -a --altpkinit unixname
        -E --no-eku
        -K --check-kdc-eku
        -L --lock-status
        -o --sudo enable | disable

Setting valid options

You can use the following options with this command:

Note:   You may specify only one option at a time when running sctool.

Use this option To do this

-e, --enable

Enable smart card support by making necessary edits to the authorization database, and by creating the /etc/cacloginconfig.plist file.

-d, --disable

Disable smart card support by removing smart-card specific strings from the authorization database, and by deleting /etc/cacloginconfig.plist.

-s, --status

Show whether smart card support is enabled or disabled.

This option outputs one of these two messages:

  • .“Centrify SmartCard support is enabled” (then exits with status 0).
  • “Centrify SmartCard support is disabled” (then exits with status 1).

-u --update-upn-map [mapping]

This option specifies a field of the smart card certificate to be used as the UPN search value.

[mapping] denotes the preferred field to be used to override the default field (NT Principal Name) of the smart card certificate.

-D, --dump

Display information about the system setup and about any smart cards that are attached to the computer. For each card, this option lists the type of card and any summary information. It also enumerates all identities on the card and lists the following for each:

  • Subject name
  • UPN (if present)
  • Whether the card is trusted
  • Data signing success or not
  • Signature verification

-S, --support

Lists the same information as the --dump option and additionally lists the state of the system configuration files.

-c --clearcrls

Removes all CRLs from the keychain.

-r --revokecheck [-t] [-p] [-l]

Extra options:

 

 

-t, --type [ocsp|crl]:[none|best|cert|all]

Change certificate validation setting for method [ocsp|crl] to [none|best|cert|all].

 

ocsp :

Online Certificate Status Protocol.

 

crl :

Certificate Revocation List.

 

none :

No revocation checking is performed.

 

best :

The certificate passes unless the server returns an indica tion of a bad certificate. This setting is best for most circumstances.

 

cert :

If the URL to the revocation server is provided in the cer tificate, this setting requires a successful connection to a revocation server and no indication of a bad certificate.

Use only in a tightly controlled environment that guaran tees the presence of a CRL server or OCSP responder. If a CRL server or OCSP responder is not available, SSL and S/MIME evaluations could fail to respond.

 

all :

This setting requires successful validation of all certifi cates. Use only in a tightly controlled environment that guarantees the presence of a CRL server or OCSP responder.

If a CRL server or OCSP responder is not available, SSL and S/MIME evaluations could fail to respond.

 

-p, --priority [ocsp|crl|both]

This setting determines which method [ocsp|crl|both] is attempted first. If the first method chosen returns a suc cessful validation, the second method is not attempted.

 

-l, --localocsp [ocsp server url]

This setting overrides the OCSP server URL of certificate with [ocsp server url]

-E, --no-eku

Allow sctool to obtain Kerberos credentials even though the client certificate does not have the extended key usage attribute. This parameter must be used with the -k (--pkinit) parameter or the -a (--altpkinit) parameter.

-K --check-kdc-eku

Enables checking of the KDC certificate for the Extended Key Usage (EKU) extension "Kerberos Authentication". Do not use this option if you have not updated your KDC to include the required EKU. Enable EKU checking after updating your KDC certificate.

EKU checking is disabled by default.

This parameter must be used with the -k (--pkinit) parameter or the -a (--altpkinit) parameter

-k, --pkinit userPrincipalName

Obtain Kerberos credentials from the smart card currently in the reader and store them in the user's cache.

This option obtains a ticket granting ticket (TGT) using the public/private key pair stored on the smart card, which is intended to be used in the same manner as the kinit(1) command: to obtain or renew credentials when they are not handled automatically (such as a long login session during which the user does not lock the screen saver), or for troubleshooting. In normal usage you should never need to run sctool --pkinit.

To obtain kerberos credentials, sctool must find a certificate that matches the user, is valid for smart card login, is not expired or revoked, and is trusted by the domain. There are several ways to specify how the certificate should be found (note that only one of these options is used; sctool does not try the later options if an earlier option fails to find a certificate):

  • If a UPN is specified on the command line, the user's keychains and the smart card in the reader (if any) are searched for a valid certificate that matches that UPN.
  • If no UPN is specified on the command line, and the CDC_SMARTCARD_TOKEN environment variable is set, the smart card named in the environment variable is searched for a valid certificate. The NT Principal Name attribute of that certificate is used as the UPN.
  • If the USER_PRINCIPAL_NAME environment variable is set, a certificate that matches that UPN is searched for in the same manner as in the first option.
  • If none of the above command-line options or environment variables are set, the sctool looks up the user in AD to obtain the UPN, and searches for a matching certificate in the same manner as in the first option.

 

While sctool --pkinit can use certificates that are stored in an on-disk keychain rather than a smart card, only use with a smart card is officially supported.

If no suitable certificate is found, sctool prints an error and exits with status 1. Otherwise, it checks whether the computer is operating in disconnected mode. If so, sctool immediately exits with status 2, since Kerberos tickets cannot be obtained in disconnected mode. This allows the authorization mechanism to permit smart card login in disconnected mode, while still verifying that the certificate on the smart card is valid and trusted.

If the computer is connected to the domain, sctool contacts the domain controller to obtain a TGT using the associated private key. If this fails, sctool prints an error and exits with status 1.

If the user’s password has expired, sctool may be unable to retrieve a TGT and will issue the message:

krb5_get_init_creds_pkinit failed: Password has expired

To resolve this issue, edit the user’s ADUC Properties page by clicking the Account tab and checking one or both of the following options:
Account option: Smart card is required for interactive login
Password never expires.

-a --altpkinit unixName

Obtain Kerberos credentials from a multi-user smart card currently in the reader and store them in the user's cache. Because the card is configured for multiple accounts, the user is prompted to enter the user name, which the command uses to retrieve the Kerberos credentials.

-L --lock-status

Show the smart card lock status for all connected smart cards. Possible values are:

  • No smart card inserted
  • Authentication attempts remaining:
  • Card is locked

-o --sudo enable | disable

  

Examples

Display information about the smart cards attached to the computer:

#sudo sctool -D
Password:

Enable smart card support:

#sudo sctool -e
Password: