AppleScript in a Nutshell-@Team LiB

Keychain Scripting

As I mentioned before, a keychain is a password file or database that is stored in encrypted form in startup disk:System Folder:Preferences:Keychains. The scripting of keychains, which store important passwords for entry to systems such as local networks, is accomplished through the Keychain Scripting software that is included with the scripting additions in the startup disk:System Folder:Scripting Additions folder. Figure 12-1 shows the checkbox that allows you to add a passphrase for an encrypted file to a keychain. You script the Keychain Scripting application just as you would target any other program, such as by enclosing Keychain Scripting commands in tell statements.

Syntax

tell app "Keychain Scripting"
   get current keychain -- get default keychain
end tell

Dictionary commands

count keychains or keys

This command counts the number of keychains the computer system has or the number of keys in a keychain. You can have more than one keychain; for example, I have a separate keychain just for linking with other Macs on my Ethernet. One keychain is always the default or active one and receives any new keys you create (see the current keychain property of the keychain application class). If you want to count just the number of keychains, use this code:

tell app "Keychain Scripting" to count keychains

This code gets a count of keys within a keychain and returns an integer:

tell application "Keychain Scripting"
   tell keychain "MyPasses" to count keys
end tell

each class

You can use the each labeled parameter to specify the counting of keys or keychains:

count each key

delete keychain or key

You can remove a key from a keychain or delete a keychain altogether with this command. The next example deletes a certain key that involves connecting to another computer over a TCP/IP network. The script does not delete the key if the keychain is locked, which is why it is a good idea to lock the keychains whenever you are not adding or removing keys from them! This is particularly true because a malicious script can just make an index reference to a key (e.g., Internet key 1) and delete the key without knowing its actual name.

tell application "Keychain Scripting"
   delete Internet key 1 of keychain "MyPasses"
end tell

exists reference to keychain or key

This command is designed to find out whether a key or keychain exists:

set thebool to (exists keychain "BogusHacker")

Unfortunately, this command does not yet work with my version of Mac OS 9 (as of 9.0.4).

lock reference to keychain

This command locks a keychain so it cannot be accessed (for instance, by a script). If you use lock without a keychain reference, then all the keychains are locked. This code locks a particular keychain, but first finds out whether it is locked at all:

tell application "Keychain Scripting"
   if (not locked of keychain "MyPasses") then
       lock keychain "MyPasses"
   end if
end tell

You could use similar code in a utility script that makes sure all keychains are locked:

tell application "Keychain Scripting" to lock

make

Use this command to automate the generation of new keys or keychains. The new and at labeled parameters are required (unless you are making a new keychain, in which case at is not required); the rest are optional. This example makes a new Internet key in a keychain called "MyPasses":

tell application "Keychain Scripting"
   try
      make new Internet key at current keychain with properties¬
      {server:"my.yahoo.com", comment:
      "General login id for yahoo services", 
      name:"yahoo_login", account:"login_anon",  
      password:"X$50*LiL"}
      on error errmessage
      display dialog "There was an error: " & errmessage
   end try
end tell

new class

If you are making a new key, then the class can be "Internet key" (for a web login service), "AppleShare key" (for automating the username and password for a file server), or "generic key" (other key types such as passphrases for encrypted files). If you are making a new keychain, then the syntax is:

make new keychain with properties {name:"test_key", locked:false}

at location

If you are making a new key, use the at labeled parameter to specify the keychain location:

make new Internet key at current keychain...

This parameter is not necessary if you are making a new keychain rather than a new key.

with data anything

It is not necessary to use this with data parameter with the make command, since you provide the new key's or keychain's properties with the with properties parameter.

with properties record

This labeled parameter fills in the properties of the new key or keychain. This example provides the properties for linking to a file server over TCP/IP:

tell application "Keychain Scripting"
   try -- catch any errors and report the message
      make new AppleShare key at keychain "program_link"¬
      with properties {server:"iMac", zone:"192.168.10.15",¬ 
      volume:"Macintosh HD", comment:"Login for iMac",¬
      name:"iMac_ login", account:"powerpc", password:"Xi$ap%"}
      on error errmessage
      display dialog "There was an error: " & errmessage
   end try
end tell

quit

You can quit the Keychain Scripting app with this command:

tell app "Keychain Scripting" to quit

unlock reference to keychain

Unlock a keychain with this command and optionally provide a password if you do not want the Keychain Access program to display the dialog that is necessary for the user to enter the keychain's password. The example code is:

unlock keychain "prog_link" with password "Xi$ap%"

Dictionary classes

application

This class represents the Keychain Scripting program. For example, you can get the current keychain (otherwise known as the default keychain) with code such as:

tell app "Keychain Scripting" to get current keychain

name string (read-only): This property returns the string "Keychain Scripting."
current keychain reference to keychain: This property returns the name of the current or default keychain, such as "MyPasses."
version version (read-only): This property returns a string specifying the Keychain Scripting software version, such as "2.0."

keychain

This class represents a keychain that you can create with either the Keychain Access control panel or AppleScript and the Keychain Scripting program. For example, you can make a new keychain with code such as:

make new keychain with properties {name:"test_key", locked:false}

Or you can find out whether a certain keychain is locked or not with the code phrase:

get locked of current keychain

name string (read-only)

This property returns the name of the Keychain as a string, such as "MyPasses."

locked boolean (read-only)

The true/false locked property is true if the keychain is locked. The following code locks all keychains:

tell app "Keychain Scripting" to lock

key

This is the "super" class for all types of specific keys (e.g., AppleShare key) and the return value for code such as:

tell app "Keychain Scripting" to get keys of current keychain

This code returns a list of all the key objects contained by the default keychain. The return value looks something like this:

{Internet key 1 of keychain "MyPasses" of application "Keychain
Scripting", generic key 1 of keychain "MyPasses" of application "Keychain
Scripting", generic key 2 of keychain "MyPasses" of application "Keychain
Scripting", generic key 3 of keychain "MyPasses" of application "Keychain
Scripting"}. In other words, this is a reference to four different keys in the
keychain "MyPasses."

name string

This property returns the key's name as it appears in the Keychain Access control panel window.

account string

If the key involves a password (for example, a key that has an AppleShare password), then this password is returned as a string, such as "_$0iX6."

creation date date (read-only)

This creation date property returns an AppleScript date object representing the date when the key was created. The creation date appears when you click the Get Info button in the Keychain Access control panel, with a specific key selected. See the Date type information in Chapter 3.

modification date date (read-only)

This modification date property returns an AppleScript date object representing the date when the key was modified. The modification date appears when you click the Get Info button in the Keychain Access control panel, with a specific key selected. See the Date type information in Chapter 3.

description string

If there is any description involved with the key, such as if you included a description property in scripting the creation of the key, then this property holds this description as a string. The return value may be an empty string.

comment string

This value appears in the Comments text field in the Keychain Access control panel's Get Info window. This return value can also be an empty string if there are no comments associated with the key.

creator code class

This returns the Mac creator code for the icon associated with the key (i.e., as it is displayed in the Keychain Access control panel). Using code such as:

get creator code of generic key 1 of keychain "MyPasses"

I get a return value in raw data:

<<class ppcx>>

file type class

This returns the key's Mac file type, which is used to match the key with a specific icon. Using code such as:

get file type of generic key 1 of keychain "MyPasses"

I get a return value in raw data:

<<class genp>>

Chapter 3 describes the Data data type.

custom icon boolean

This returns true if the key uses a custom icon:

get custom icon of generic key 1 of keychain "MyPasses"

invisible boolean

This property returns false if the key is visible to the user.

negative boolean

This property returns true if the key prevents the keychain from being used.

password string

If the key is associated with a password (as most are), this property contains the password string. Get all passwords associated with an unlocked keychain as a list type with the following code (if your keychain is called "MyPasses"):

get password of (keys of keychain "MyPasses")

AppleShare key

This class is a subclass of the key class, so it has the same properties as the key class in addition to the following specialized properties. For example, if you use the Chooser to connect to another computer or file server via TCP/IP, and check the Add to Keychain checkbox, then an Appleshare key is automatically created for that file server and added to the default keychain.

zone string: This string property identifies the AppleTalk zone or the IP address (as in "192.168.0.5") if the AppleShare key connects to a computer via the TCP/IP protocol.
server string: This property returns the name of the file server associated with the key, as in "iMacHome."
volume string:: This string identifies the volume that is mounted on the desktop when you use this AppleShare key to connect to another computer.

Internet key

This class represents a type of key that is designed to automatically log you on to a server. As a subclass of the key class, it also inherits the properties of that class. In other words, an Internet key also has creation-date and modification-date properties, along with its five custom props.

server string: This string returns the server address or hostname of the key to a web server, as in my.yahoo.com for a (hypothetical) login key to Yahoo.com's servers.
path string: This property returns a string to a file or directory, such as finance/get_stock.cgi if my.yahoo.com/finance/get_stock.cgi existed. If there is no URL path after the hostname (my.yahoo.com) then this property is an empty string.
security domain string: This string is empty if there is no specified security-domain property for the Internet key.
port integer: This represents the TCP/IP port number, as in 80 for a typical web server.
protocol constant: The protocol can be any of the following constants: FTP/HTTP/IRC/NNTP/POP3/SMTP/SOCKS/IMAP/LDAP/AppleTalk/AFP/Telnet. For example, if the hypothetical Internet key was used for gaining access to an File Transfer Protocol server, then FTP would be the protocol.
authentication constant: This property can be any one of the following constants: NTLM/MSN/DPA/RPA/HTTP digest/default.

generic key

The key class is considered generic if it is not an Appleshare or an Internet key, such as an Apple File Security password. For example, if you encrypt a file and opt to store the encryption passphrase or password for that file in a keychain, this would be considered a generic key. You could reference the key in code by its index:

tell app "Keychain Scripting" to get service of generic key 1 of
keychain "MyPasses"

service string: This is a string that usually contains the name of the key, such as the filename for a file that has been encrypted by Apple File Security and added to a keychain.