14.1. Import

Seed files that contain the secret keys of hardware tokens can be imported to the system via the menu Token -> Import.

The default import options are to import SafeNet XML files, OATH CSV files, Yubikey CSV files or PSKC files.

14.1.1. GPG Encryption

You can import GPG-encrypted seed files. All files mentioned below can be encrypted this way.

privacyIDEA needs its own GPG key. You may create one like this:

mkdir /etc/privacyidea/gpg
GNUPGHOME=/etc/privacyidea/gpg gpg --gen-key

Then make sure that the directory /etc/privacyidea/gpg is owned by the user privacyidea and has the mode 700 (chmod 700).

Now you can export the public key and hand it to your token vendor:

GNUPGHOME=/etc/privacyidea/gpg gpg -a --export <keyid>

Now the token vendor can send the seed file GPG encrypted. You do not need to decrypt the file and store the decrypted file on a network folder. Just import the GPG encrypted file to privacyIDEA!

Note

Using the key PI_GNUPG_HOME in pi.cfg you can change the default above mentioned GNUPGHOME directory.

Note

privacyIDEA imports an ASCII armored file. The file needs to be encrypted like this:

gpg -e -a -r <keyid>  import.csv

14.1.2. OATH CSV

This is a very simple CSV file to import HOTP, TOTP, OCRA or TAN tokens. You can also convert your seed easily to this file format, to import the tokens.

The file format for TOTP tokens looks like this:

<serial>, <seed>, TOTP, <otp length>, <time step>

For HOTP tokens like:

<serial>, <seed>, [HOTP, <otp length>, <counter>]

For OCRA tokens it looks like this:

<serial>, <seed>, OCRA, <ocra suite>

serial is the serial number of the token that will also be used to identify the token in the database. Importing the same serial number twice will overwrite the token data.

seed is the secret key, that is used to calculate the OTP value. The seed is provided in a hexadecimal notation. The hash algorithm is derived from the length of the seed, see the note below.

type is either HOTP, TOTP or OCRA.

otp length is the length of the OTP value generated by the token. This is usually 6 or 8.

time step is the time step of TOTP tokens. This is usually 30 or 60.

ocra suite is the ocra suite of the OCRA token according to [1].

For TAN tokens it looks like this:

<serial>, <n/a>, TAN, <list of tans>

The list of tans is a whitespace separated list.

Note

The hash algorithm is derived from the length of the hexadecimal seed: 56 characters select SHA224, 64 characters SHA256, 96 characters SHA384 and 128 characters SHA512. With any other length SHA1 is used.

14.1.2.1. Import format version 2

Import format version 2 lets you prepend the user to whom the imported token should be assigned.

The file format needs to start with the first line:

# version: 2

and the first three columns will be the user:

<username>, <resolver>, <realm>, <serial>, <seed>, <type>, ...

Note

The import will bail out, if a specified user does not exist.

14.1.3. Yubikey CSV

Here you can import the CSV file that is written by the YubiKey Personalization GUI [2], in the traditional format or in the Yubico format. The tool has reached its end of life, but files written with it can still be imported. privacyIDEA imports YubiKeys in Yubico OTP (AES) mode and in OATH-HOTP mode. Lines for the static password mode are skipped.

HOTP tokens from a Yubikey CSV file always get the OTP length 6. For YubiKeys programmed with 8 digits, use a PSKC file or the Flexible format described in YubiKey Enrollment Tools and import it as OATH CSV. The Yubico format does not record the slot: all serials end in _X, so if both slots of a YubiKey are programmed in the same mode, only the later line is imported.

../../_images/yubikey1.png

Note

The Yubikey in HOTP mode defaults to the Hash algorithm SHA1.

For more information about enrolling Yubikeys see YubiKey Enrollment Tools.

14.1.4. PSKC

The Portable Symmetric Key Container is specified in [3]. OATH compliant token vendors provide the token seeds in a PSKC file. privacyIDEA lets you import PSKC files. All necessary information (OTP length, Hash algorithm, token type) is read from the file.

Note

In PSKC the Hash algorithm is specified in the <Suite> tag. If it is not specified, SHA1 is used as the default. The length of the seed is not used to determine the Hash algorithm.

PSKC files can be encrypted - either with a password or an AES key. You can provide this during the upload: the Pre Shared Key as 32 hexadecimal characters (128 bit), or the Password, from which the key is derived with PBKDF2 using the parameters given in the file. Encrypted values must use AES-128-CBC.

For encrypted files, the Verification Method for the Authenticity of Imported Tokens (API parameter pskcValidateMAC) decides how the MAC of the encrypted values is handled:

  • Abort operation on unverifiable token (check_fail_hard, default): if the MAC of one token does not match, no token of the file is imported.

  • Skip tokens that can not be verified (check_fail_soft): tokens with a wrong MAC are not imported, the others are.

  • Do not verify the authenticity (no_check): the MAC is not checked.

14.1.5. SafeNet XML

SafeNet (now part of Thales), formerly Aladdin, provided seed files in their own XML format. This is the format to choose, if you have a file, that looks like this:

<Tokens>
    <Token serial="00040008CFA5">
    <CaseModel>5</CaseModel>
    <Model>101</Model>
    <ProductionDate>02/19/2009</ProductionDate>
    <ProductName>Safeword Alpine</ProductName>
    <Applications>
    <Application ConnectorID="{ab1397d2-ddb6-4705-b66e-9f83f322deb9}">
    <Seed>123412354</Seed>
    <MovingFactor>1</MovingFactor>
    </Application>
    </Applications>
    </Token>

    <Token ...>
    ...
    </Token>
 </Tokens>

Note

The hash algorithm defaults to SHA1, unless the seed is 64 characters long; then SHA256 is assumed.

Note

This format is deprecated. SafeNet (Thales) nowadays might provide you with an XML file, which is probably a PSKC file. Please check the file contents!