TrustPort eSign PRO: Command Line - Managing storages on disk

When using this mode, you are working directly with storage on a disk. All parameters for working over files may be used here, except of -r and -s which are meaningful only for external files. Let's look on the example that signs file on storage and redirects output to another (external) file: esign -f file -m sgn -o output.sgn .

Specifying the mode

This is again done with -m mode_shortcut or --mode=mode_shortcut parameter. Mode shortcut can be one of the follows:

  • sgn ... signs a file,
  • enc ... encrypts a file,
  • sge ... signs and encrypts a file,
  • dec ... decrypts and/or veryfies a file,
  • esg ... creates extra signature,
  • tsa ... creates a time stamp (only for already signed files),
  • sgt ... signs a file and addes a time stamp,
  • tst ... creates a file with a time stamp.

Specifying storage type

If you want to specify a storage type, you can do so through -c storage_type or --choosestorage=storage_type parameters, where storage_type is one of the following alternatives:

Specifying the storage

Is done on command line by entering -l storage_name or --localstorage=storage_name parameter. It's necessary to give the storage type unless a local storage is desired. If no storage is selected, a default one is used. Note that you can not under any circumstances affect the default storage by preferred storage in the configuration. For esign.exe installed in C:\Program Files\TrustPort eSign PRO\bin, default storage is saved in: C:\Program Files\TrustPort eSign PRO\storage, i.e. always in ..\storage directory from given program. This storage can not be relocated anywhere else. After the installation, this storage is identified as Default local . Use parameter mentioned above to use any other storage when working with the program.

Example of encrypting a file on a local storage esign -f file.txt -l storage -c local -m enc .

Adding a storage

A new storage can be added with -A storage_name or --addstorage=storage_name . When no further parameters are given, the path to the new storage is generated automatically.

Using parameter --storagepath=path a path to such local storage may be set, e.g. esign -A "my_new_storage" --storagepath=c:\storage\new_storage .

Removing a storage

When a storage is not useful anymore, it's possible to remove it. You can also choose to physically remove the storage data from disk. To remove storage, type -D storage_name or --deletestorage=storage_name , e.g. esign -D "my_new_storage" . Because default local storage exists all the time, if deleted it will be recreated when next operation over the storage is executed. When removing a storage, it's possible to physically delete contents from disk with --forcedelete parameter.

Listing of storage content

If you need to know the contents of a storage, use --storagecontent , e.g. esign -l "my_storage" --storagecontent .

Importing a file into a storage

It's possible to import any file of supported type into the storage. Supported file types are .CER , .BIN or .PEM containing one recipient certificate, .P7C or .P7B with one or more recipient's certificates, .P12 and .PFX file types containing key pair and file of type .CRL with a list of revoked certificates. If CRL file is being imported, the information contained within is immediately applied on the storage. Parameter for start importing is -i -f filename or --import --file=filename , e.g. esign -i -f key_pair.p12 --no-password .

Alias for key ( -K name or --keyalias=name ), certificate ( -E name or --certifalias=name ) and CRL ( --crlalias=name ) can be set.

Applying CRL

If you want to directly apply CRL, use -a or --applyCRL parameter. If any revoked certificates will be found, you'll be given a note and you will be able to delete them. This function, available for local storages only, is usable in case you've imported new certificate into the storage after CRL had been applied.

Checking validity of objects in a storage

If you want to check validity of objects in a storage, use --verifysigns . The operation checks and sets validity of every certificate there. It also looks for any CRLs, checks and sets their validity and finally applies them on every certificate in storage. If any revoked certificates should be found then, you will be given a chance to delete them.

Certificate's Validity property is set during the validity check.

Exporting into a file

It is possible to export an object into a file of various types. One certificate may be exported into .CER , .BIN or .PEM file. One or more certificates can be exported into a .P7C or .P7B file. Types .P12 and .PFX are protected by password and can be used to hold a key pair. Exporting itself is done through -e -f file or --export --file=filename , where the file parameter specifies the name of file you want to export objects into. Use -T type or --filetype=type to choose the type of that file, where type determines type of resulting file. It's possible to choose internal filetype too. Default internal type is binary, but using -F filetype or --filetype=filetype you can choose BASE64 or BASE64 with trailers.

Example of exporting key pair into keypair.p12 in BASE64 with trailers format: esign -e -f "keypair.p12" -T p12 -F TRAIL .

You can precise the selection with -O pattern or --object=pattern . A complete certificate path is passed when key pair is exported.

Displaying object's details

Use -d or --details parameter to make the program output object details. With -O pattern it's possible to more precisely specify object you are interested in and the -T type parameter lets you choose the type of object (private key, certificate, CRL). Example: esign -d -O DSA -l storage -T key .

Generating key pair or a certificate request

With parameter -g or --generate a new object can be generated. You can affect resulting key pair or certificate request with specifying further details, like name of the private key, its algorithm or way of generating,... For example: esign -g -K key_alias -E certificate_alias -k 1024 -b DSA .

Name of the new object

You can specify a name for newly generated object. For private key, it's -K key_alias or --keyalias=key_alias , for certificate it's -E cert_alias or --certalias=cert_alias . CLR alias is specified like --crlalias=CRL_alias . It's understood that aliases have to be unique inside the storage.

Supported algorithms

The --storageinfo parameter helps you with obtaining the information about supported algorithms. Unless -c storage_type or --choosestorage=storage_type is given, the operation will be executed on the local storage.

Specifying the algorithm type

It's also possible to choose algorithm of public key before generating starts with -b type and --pubkeyalgorithm=type , where type is one of RSA, ELLIPTIC, DSA or DH values. Further, with -n type or --signalgorithm=type it's possible to choose algorithm used for signing, where type is one of SHA-1, SHA-256, SHA-512, SHA-256, RIPEMD-160 or MD-5 values.

Private key length

If you've generated key pair and you need to change key length (or if you want to change key algorithm), you need to use parametr -k length or --keylength=length to set length of key. It's advisable to know permitted algorithm/key length combinations. For example, you can not make DSA or DH keys 512 or 768 length, but you are free to do such keys with RSA.

Creating a certificate or certificate request

Using the -M type or --certificatemode=type parameters you can choose among self-signed certificate (default option) or request to create a request for certificate.

Methods of creating a key pair

The -G type or --generationmode=type lets you select how the key pair should be created. Possible types are into-storage - default option which generates the pair in memory and then imports it into the storage, by-storage - used only for tokens and chip-cards, save-to-file - for saving the pair into a .p12 file and a special mode save-separate , which separately creates a certificate and a key stored in OpenSSL format.

Filetype

Type of generated or exported file is selectable through -F type or --filetype=type parameter. Permitted values for the type are: PEM - BASE64 encoding, TRAIL - BASE64 with trailers encoding and BIN - the binary encoding.

Entering a password

Sometimes (like when generating), you need to enter private key password or file password. You can choose among two options how the password should be used:

  • When no password is set (that is the password is blank), the --no-password parameter has to be used,
  • When non-blank password is set, --password=your_password parameter has to be used. When both parameters are used, this one takes priority.

Validity of certificate

There's a validity value assigned for every certificate. One year is set by default, but it's possible to prolong it with the --validity=year parameter.

Deleting objects in a storage

If you want to delete a object in a storage, use either of the forms -R alias or --removeobject=alias . Note that object's type must be specified ( -T type or --storageobject ), because two objects of different type (like e.g. a key and a certificate) can have same name. Example: esign -R alias -T key .

If you delete a key, appropriate certificate is also removed, because without the private key such certificate is useless anyway. There is a --deleteonlykey parameter for the case you really want to remove private key only

Specifying object type

For type of intended object specifing use the -T object_type or --storageobject=object_type , where object_type defines required object type. Following values can be typed in as object_type : key , certificate , keypair , crl , storage , cer , p7c and p12 .

This parameter is used in more contexts, therefore it has many various possible values. However, this doesn't mean that any of these values may be used anywhere. Exporting is permitted for basic types only, i.e. cer, p7c, p12 and crl. Displaying details can be executed only for: key, certificate, crl for objects within a storage and cer, p7c, p12 and crl for files. Only storage, key, certificate and crl types may be renamed and key, certificate, keypair and crl may be deleted.

Changing a password

The application lets you change password for either private keys or .p12 files. For a password of private key changing use -P alias or --changepassword=alias . For a password of .p12 file changing use -p filename or --changep12password=filename .

For password changing and specifing of a new one at the same time use --newpassword=password . Example: esign -P key --password p14%_l --newpassword SaDz15_Q+ . Of course, --no-password is also applicable here.

Changing name

For name of some object within a storage changing or changing of name for a storage itself, use -C name or --changename=name . Parameter name specifies the name of object you want to change name for. Also it's necessary to give the object type using -T type or --storageobject=type . Example: esign -C default -T storage

You might want to specify a new object's name (ahead a name changing) and you can do it with -N new_name or --newname=new_name parameter, e.g. esign -C default -T storage -N "my storage"

Selecting by pattern

A situation when you want to select some object, but you either don't know his parameters exactly or you only know his name and therefore you wouldn't like to be choosing among all the objects in the storage. That's when parameters -O pattern or --object=pattern come handy. For example you have to encrypt the file data.doc addressed for John Smith. You have John's certificate containing his name, but you don't know the name of the certificate: esign -f data.doc -m enc -O "John Smith" .

In case you know object's name exactly, you can specify so with -w or --wholename . With this parameter, only objects matching given criterion exactly are found (which differs from the default behavior when even partial match is considered to be satisfying). Let's have e.g. two certificates: first containing name John Smith, second simply Smith. If you execute -O Smith , both certificates will be found, however with -w added, only the second one will be found.

There's exactly one occasion to use -B pattern or --object2=pattern parameters and that is when -m sge (sign and encrypt mode) is set. Object selected by -O is then used for signature, while -B for encrypting. Example: esign -f data.doc -m sge -O RSA512 -B "John Smith" .

Setting a Time Stamp Authority

For adding the Time Stamp you need to have properly assigned and set the Time Stamp Authority (TSA). It may be done through -I address:port or --timestampauthority=address:port parameters to specify the address and the port on which the TSA accepts requests and sends answers.

You need to select a storage containing TSA certificate when you are setting the Time Stamp Authority. With --authorityname=name parameter, you can enter the name of TSA. The default storage is searched by default, but this behavior may be overridden with -l . Certificate name may be set with the -E parameter. Next you have to specify the --addTSA parameter.

Example: esign -I "http://time.trustport.cz:8000/" -E TSAcertif --authorityname=TSA --addTSA .

Working with a Time Stamp

A Time Stamp may be attached to any encrypted ( sgn mode) or a separate signature ( esg mode) file. You however have to choose the Time Stamp Authority either in --authorityname="AEC TSA" form or with -I address:port or --timestampauthority=address:port parameters. Authority's certificate may be chosen with --TSAcertif=certificate parameter.

Example:

  • esign -f file.sgn -m tsa -I "http://time.trustport.cz:8000/" --TSAcertif=TSAcertificate.cer ... direct Time Stamp Authority selection
  • esign -f file.sgn -m tsa -I "http://time.trustport.cz:8000/" ... selecting already set Time Stamp Authority by the address
  • esign -f file.sgn -m tsa --authorityname=TSA ... selecting already set Time Stamp Authority by its name

These operations may however be done all at once through modes sgt or esg with appropriate parameters.

Example: esign -f file -m est -s key_pair.p12 -I "http://time.trustport.cz:8000/" --TSAcertif=TSAcertificate.cer .

A new product feature lets you create only a Time Stamp with a HASH of some file using the -m tst mode. Of course, parameters of used Time Stamp Authority are again necessary here.

Example: esign -f file -m tst -I "http://time.trustport.cz:8000/" --TSAcertif=TSAcertificate.cer .

However, when operating on storage, you don't have to specify TSA's name, because preset TSA is automatically selected. This preset value may be changed in configuration, section TimeStamp.

Example: esign -f file -m tst .

Related references

Main Page
Command Line
Operations over files
Operations over tokens and chip-cards
Working with LDAP and hybrid storages


Copyright 2010, TrustPort, a.s., All rights reserved.