Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PKCS15-INITPKCS15-(1)	   OpenSC ToolsOpenSC Tools	 PKCS15-INITPKCS15-(1)

NAME
       pkcs15-init - smart card	personalization	utility

SYNOPSIS
       pkcs15-init [OPTIONS]

DESCRIPTION
       The pkcs15-init utility can be used to create a PKCS #15	structure on a
       smart card, and add key or certificate objects. Details of the
       structure that will be created are controlled via profiles.

       The profile used	by default is pkcs15. Alternative profiles can be
       specified via the -p switch.

PIN USAGE
       pkcs15-init can be used to create a PKCS	#15 structure on your smart
       card, create PINs, and install keys and certificates on the card. This
       process is also called personalization.

       An OpenSC card can have one security officer PIN, and zero or more user
       PINs. PIN stands	for Personal Identification Number, and	is a secret
       code you	need to	present	to the card before being allowed to perform
       certain operations, such	as using one of	the stored RSA keys to sign a
       document, or modifying the card itself.

       Usually,	PINs are a sequence of decimal digits, but some	cards will
       accept arbitrary	ASCII characters. Be aware however that	using
       characters other	than digits will make the card unusable	with PIN pad
       readers,	because	those usually have keys	for entering digits only.

       The security officer (SO) PIN is	special; it is used to protect meta
       data information	on the card, such as the PKCS #15 structure itself.
       Setting the SO PIN is optional, because the worst that can usually
       happen is that someone finding your card	can mess it up.	To extract any
       of your secret keys stored on the card, an attacker will	still need
       your user PIN, at least for the default OpenSC profiles.	However, it is
       possible	to create card profiles	that will allow	the security officer
       to override user	PINs.

       For each	PIN, you can specify a PUK (also called	unblock	PIN). The PUK
       can be used to overwrite	or unlock a PIN	if too many incorrect values
       have been entered in a row.

       For some	cards that use the PKCS#15 emulation, the attributes of
       private objects are protected and cannot	be parsed without
       authentication (usually with User PIN). This authentication need	to be
       done immediately	after the card binding.	In such	cases --verify-pin has
       to be used.

MODES OF OPERATION
   Initialization
       This is the first step during card personalization, and will create the
       basic files on the card.	To create the initial PKCS #15 structure,
       invoke the utility as

       pkcs15-init --create-pkcs15

       You will	then be	asked for the security officer PIN and PUK. Simply
       pressing	return at the SO PIN prompt will skip installation of an SO
       PIN.

       If the card supports it,	you should erase the contents of the card with
       pkcs15-init --erase-card	before creating	the PKCS#15 structure.

   User	PIN Installation
       Before installing any user objects such as private keys,	you need at
       least one PIN to	protect	these objects. you can do this using

       pkcs15-init --store-pin --id " nn

       where nn	is a PKCS #15 ID in hexadecimal	notation. Common values	are
       01, 02, etc.

       Entering	the command above will ask you for the user's PIN and PUK. If
       you do not wish to install an unblock PIN, simply press return at the
       PUK prompt.

       To set a	label for this PIN object (which can be	used by	applications
       to display a meaningful prompt to the user), use	the --label command
       line option.

   Key generation
       pkcs15-init lets	you generate a new key and store it on the card. You
       can do this using:

       pkcs15-init --generate-key " keyspec " --auth-id	" nn

       where keyspec describes the algorithm and length	of the key to be
       created,	such as	rsa/512. This will create a 512	bit RSA	key.
       Currently, only RSA key generation is supported.	Note that cards
       usually support just a few different key	lengths. Almost	all cards will
       support 512 and 1024 bit	keys, some will	support	768 or 2048 as well.

       nn is the ID of a user PIN installed previously,	e.g.  01.

       In addition to storing the private portion of the key on	the card,
       pkcs15-init will	also store the public portion of the key as a PKCS #15
       public key object.

   Private Key Upload
       You can use a private key generated by other means and upload it	to the
       card. For instance, to upload a private key contained in	a file named
       okir.pem, which is in PEM format, you would use

       pkcs15-init --store-private-key okir.pem	--id 45	--auth-id 01

       In addition to storing the private portion of the key on	the card,
       pkcs15-init will	also store the public portion of the key as a PKCS #15
       public key object.

       Note that usage of --id option in the pkcs15-init commands to generate
       or to import a new key is deprecated. Better practice is	to let the
       middleware to derive the	identifier from	the key	material.
       (SHA1(modulus) for RSA, SHA1(pub) for DSA, ...).	This allows easily set
       up relation between 'related' objects (private/public keys and
       certificates).

       In addition to the PEM key file format, pkcs15-init also	supports DER
       encoded keys, and PKCS #12 files. The latter is the file	format used by
       Netscape	Navigator (among others) when exporting	certificates to	a
       file. A PKCS #12	file usually contains the X.509	certificate
       corresponding to	the private key. If that is the	case, pkcs15-init will
       store the certificate instead of	the public key portion.

   Public Key Upload
       You can also upload individual public keys to the card using the
       --store-public-key option, which	takes a	filename as an argument. This
       file is supposed	to contain the public key. If you don't	specify	a key
       file format using the --format option, pkcs15-init will assume PEM
       format. The only	other supported	public key file	format is DER.

       Since the corresponding public keys are always uploaded automatically
       when generating a new key, or when uploading a private key, you will
       probably	use this option	only very rarely.

   Certificate Upload
       You can upload certificates to the card using the --store-certificate
       option, which takes a filename as an argument. This file	is supposed to
       contain the PEM encoded X.509 certificate.

   Uploading PKCS #12 bags
       Most browsers nowadays use PKCS #12 format files	when you ask them to
       export your key and certificate to a file.  pkcs15-init is capable of
       parsing these files, and	storing	their contents on the card in a	single
       operation. This works just like storing a private key, except that you
       need to specify the file	format:

       pkcs15-init --store-private-key okir.p12	--format pkcs12	--auth-id 01

       This will install the private key contained in the file okir.p12, and
       protect it with the PIN referenced by authentication ID 01. It will
       also store any X.509 certificates contained in the file,	which is
       usually the user	certificate that goes with the key, as well as the CA
       certificate.

   Secret Key Upload
       You can use a secret key	generated by other means and upload it to the
       card. For instance, to upload an	AES-secret key generated by the	system
       random generator	you would use

       pkcs15-init --store-secret-key /dev/urandom --secret-key-algorithm
       aes/256 --auth-id 01

       By default a random ID is generated for the secret key. You may specify
       an ID with the --id if needed.

OPTIONS
       --version,
	   Print the OpenSC package release version.

       --card-profile name, -c name
	   Tells pkcs15-init to	load the specified card	profile	option.	You
	   will	rarely need this option.

       --create-pkcs15,	-C
	   This	tells pkcs15-init to create a PKCS #15 structure on the	card,
	   and initialize any PINs.

       --serial	SERIAL
	   Specify the serial number of	the card.

       --erase-card, -E
	   This	will erase the card prior to creating the PKCS #15 structure,
	   if the card supports	it. If the card	does not support erasing,
	   pkcs15-init will fail.

       --erase-application AID
	   This	will erase the application with	the application	identifier
	   AID.

       --generate-key keyspec, -G keyspec
	   Tells the card to generate new key and store	it on the card.
	   keyspec consists of an algorithm name (currently, the only
	   supported name is RSA), optionally followed by a slash and the
	   length of the key in	bits. It is a good idea	to specify the key ID
	   along with this command, using the id option, otherwise an
	   intrinsic ID	will be	calculated from	the key	material. Look the
	   description of the 'pkcs15-id-style'	attribute in the
	   'pkcs15.profile' for	the details about the algorithm	used to
	   calculate intrinsic ID. For the multi-application cards the target
	   PKCS#15 application can be specified	by the hexadecimal AID value
	   of the aid option.

       --pin pin, --puk	puk, --so-pin sopin, --so-puk sopuk
	   These options can be	used to	specify	the PIN/PUK values on the
	   command line. If the	value is set to	env:VARIABLE, the value	of the
	   specified environment variable is used. By default, the code	is
	   prompted on the command line	if needed.

	   Note	that on	most operation systems,	any user can display the
	   command line	of any process on the system using utilities such as
	   ps(1). Therefore, you should	prefer passing the codes via an
	   environment variable	on an unsecured	system.

       --no-so-pin,
	   Do not install a SO PIN, and	do not prompt for it.

       --profile name, -p name
	   Tells pkcs15-init to	load the specified general profile. Currently,
	   the only application	profile	defined	is pkcs15, but you can write
	   your	own profiles and specify them using this option.

	   The profile name can	be combined with one or	more profile options,
	   which slightly modify the profile's behavior. For instance, the
	   default OpenSC profile supports the openpin option, which installs
	   a single PIN	during card initialization. This PIN is	then used both
	   as the SO PIN as well as the	user PIN for all keys stored on	the
	   card.

	   Profile name	and options are	separated by a + character, as in
	   pkcs15+onepin.

       --secret-key-algorithm keyspec,
	   keyspec describes the algorithm and length of the key to be created
	   or downloaded, such as aes/256. This	will create a 256 bit AES key.

       --store-certificate filename, -X	filename
	   Tells pkcs15-init to	store the certificate given in filename	on the
	   card, creating a certificate	object with the	ID specified via the
	   --id	option.	Without	supplied ID an intrinsic ID will be calculated
	   from	the certificate's public key. Look the description of the
	   'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details
	   about the algorithm used to calculate intrinsic ID. The file	is
	   assumed to contain the PEM encoded certificate. For the
	   multi-application cards the target application can be specified by
	   the hexadecimal AID value of	the aid	option.

       --store-pin, -P
	   Store a new PIN/PUK on the card.

       --store-public-key filename
	   Tells pkcs15-init to	download the specified public key to the card
	   and create a	public key object with the key ID specified via	the
	   --id. By default, the file is assumed to contain the	key in PEM
	   format. Alternative formats can be specified	using --format.

       --store-private-key filename, -S	filename
	   Tells pkcs15-init to	download the specified private key to the
	   card. This command will also	create a public	key object containing
	   the public key portion. By default, the file	is assumed to contain
	   the key in PEM format. Alternative formats can be specified using
	   --format. It	is a good idea to specify the key ID along with	this
	   command, using the --id option, otherwise an	intrinsic ID will be
	   calculated from the key material. Look the description of the
	   'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details
	   about the algorithm used to calculate intrinsic ID. For the
	   multi-application cards the target PKCS#15 application can be
	   specified by	the hexadecimal	AID value of the aid option.

       --store-secret-key filename,
	   Tells pkcs15-init to	download the specified secret key to the card.
	   The file is assumed to contain the raw key. They key	type should be
	   specified with --secret-key-algorithm option.

	   You may additionally	specify	the key	ID along with this command,
	   using the --id option, otherwise a random ID	is generated. For the
	   multi-application cards the target PKCS#15 application can be
	   specified by	the hexadecimal	AID value of the aid option.

       --store-data filename, -W filename
	   Store a data	object.

       --update-certificate filename, -U filename
	   Tells pkcs15-init to	update the certificate object with the ID
	   specified via the --id option with the certificate in filename. The
	   file	is assumed to contain a	PEM encoded certificate.

	   Pay extra attention when updating mail decryption certificates, as
	   missing certificates	can render e-mail messages unreadable!

       --delete-objects	arg, -D	arg
	   Tells pkcs15-init to	delete the specified object.  arg is
	   comma-separated list	containing any of privkey, pubkey, secrkey,
	   cert, chain or data.

	   When	data is	specified, an ---application-id	must also be
	   specified, in the other cases an --id must also be specified

	   When	chain is specified, the	certificate chain starting with	the
	   cert	with specified ID will be deleted, until there's a CA
	   certificate that certifies another cert on the card

       --change-attributes arg,	-A arg
	   Tells pkcs15-init to	change the specified attribute.	 arg is	either
	   privkey, pubkey, secrkey, cert or data. You also have to specify
	   the --id of the object. For now, you	can only change	the --label,
	   e.g:

						       pkcs15-init -A cert --id	45 -a 1	--label	Jim

       --use-default-transport-keys, -T
	   Tells pkcs15-init to	not ask	for the	transport keys and use default
	   keys, as known by the card driver.

       --sanity-check, -T
	   Tells pkcs15-init to	perform	a card specific	sanity check and
	   possibly update procedure.

       --reader	arg, -r	arg
	   Number of the reader	to use.	By default, the	first reader with a
	   present card	is used. If arg	is an ATR, the reader with a matching
	   card	will be	chosen.

       --verbose, -v
	   Causes pkcs15-init to be more verbose. Specify this flag several
	   times to enable debug output	in the OpenSC library.

       --wait, -w
	   Causes pkcs15-init to wait for a card insertion.

       --use-pinpad
	   Do not prompt the user; if no PINs supplied,	pinpad will be used.

       --puk-id	ID
	   Specify ID of PUK to	use/create

       --puk-label LABEL
	   Specify label of PUK

       --public-key-label LABEL
	   Specify public key label (use with --generate-key)

       --cert-label LABEL
	   Specify user	cert label (use	with --store-private-key)

       --application-name arg
	   Specify application name of data object (use	with
	   --store-data-object)

       --aid AID
	   Specify AID of the on-card PKCS#15 application to be	binded to (in
	   hexadecimal form)

       --output-file filename -o filename,
	   Output public portion of generated key to file

       --passphrase PASSPHRASE
	   Specify passphrase for unlocking secret key

       --authority
	   Mark	certificate as a CA certificate

       --key-usage arg -u arg,
	   Specifies the X.509 key usage.  arg is comma-separated list
	   containing any of digitalSignature, nonRepudiation,
	   keyEncipherment, dataEncipherment, keyAgreement, keyCertSign,
	   cRLSign. Abbreviated	names are allowed if unique (e.g.  dataEnc).

	   The alias sign is equivalent	to
	   digitalSignature,keyCertSign,cRLSign

	   The alias decrypt is	equivalent to keyEncipherment,dataEncipherment

       --finalize -F,
	   Finish initialization phase of the smart card

       --update-last-update
	   Update 'lastUpdate' attribute of tokenInfo

       --ignore-ca-certificates
	   When	storing	PKCS#12	ignore CA certificates

       --update-existing
	   Store or update existing certificate

       --extractable
	   Private key stored as an extractable	key

       --user-consent arg
	   Specify user-consent.  arg is an integer value. If >	0, the value
	   specifies how many times the	object can be accessed before a	new
	   authentication is required. If zero,	the object does	not require
	   re-authentication.

       --insecure
	   Insecure mode: do not require a PIN for private key

       --md-container-guid GUID
	   For a new key specify GUID for a MD container

       --help -h,
	   Display help	message

SEE ALSO
       pkcs15-profile(5)

AUTHORS
       pkcs15-init was written by Olaf Kirch <okir@suse.de>.

openscopensc			  02/28/2021		 PKCS15-INITPKCS15-(1)

NAME | SYNOPSIS | DESCRIPTION | PIN USAGE | MODES OF OPERATION | OPTIONS | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pkcs15-init&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help