=pod

=head1 NAME

ahab_pki_tree, hab4_pki_tree - generate a basic PKI tree for secure boot on NXP i.MX processors

=head1 SYNOPSIS

=over 4

=item AHAB

B<ahab_pki_tree> B<-existing-ca> I<yn> [B<-ca-key> I<name> B<-ca-cert> I<name>] B<-kt> I<algo>
B<-kl> I<param> B<-duration> I<years> B<-num-srk> I<nr> B<-srk-ca> I<yn> [B<--help>]

=item HABv4

B<hab4_pki_tree> B<-existing-ca> I<yn> [B<-ca-key> I<name> B<-ca-cert> I<name>] B<-kt> I<algo>
B<-kl> I<param> B<-duration> I<years> B<-num-srk> I<nr> B<-srk-ca> I<yn> [B<--help>]

=back

=head1 NOTE

This manpage is a short description of NXP B<ahab_pki_tree> and B<hab4_pki_tree>.
For a detailed discussion refer to the Code Signing Tool User Guide UG10106, section 4.1.1.
The user guide can be obtained from www.nxp.com and is excluded from Debian for copyright reasons.

=head1 DESCRIPTION

B<ahab_pki_tree> and B<hab4_pki_tree> generate a basic PKI tree.
The PKI tree consists of a Certificate Authority (CA) and one or more Super Root Keys (SRK).
With the ahab variant, each SRK has one subordinate Signing Key (SGK).
The hab4 variant creates one subordinate Command Sequence File (CSF) key and one image (IMG) key for each SRK.
Additional keys can later be added with the B<add_key> tool.

Following files and directories relative to the current working directory are
expected or are created if not existing.

=over 4

=item crts

Directory where X.509 public key certificates for CA, SRK, SGK, CSF and IMG are searched and created.
All certificates are in PEM and DER format.

The naming convention is I<name>.pem, where I<name> refers to the argument
supplied with B<-ca-cert> I<name> and B<-ca-key> I<name>.

=item keys

Directory where private keys corresponding to the certificates in crts are searched and created.
All keys are in PKCS #8 syntax and are encoded to PEM and DER format.

=item keys/key_pass.txt

Text file containing a password to protect private keys.
The password is repeated twice, for example

  my_password
  my_password

The same password is used for all private keys.
Default password is C<test>.

=back

The tools will load general settings from the system wide OpenSSL configuration file.

=head1 OPTIONS

=over 4

=item B<-existing-ca> I<yn>

B<y> to use an existing CA key, or B<n> to generate CA key and certificate from scratch.
If B<y>, the B<-ca-key> and B<-ca-cert> options must be specified.

=item B<-ca-key> I<name>

If B<-existing-ca> was B<y>, this option specifies the existing CA key.

=item B<-ca-cert> I<name>

If B<-existing-ca> was B<y>, this option specifies the existing CA certificate.

=item B<-kt> I<algo>

Public key algorithm to use.
One of B<rsa>, B<rsa-pss>, B<ecc>.

=item B<-kl> I<param>

For I<algo> B<ecc>, one of B<p256>, B<p384>, B<p521>.

For I<algo> B<rsa> and B<rsa-pss>, one of B<2048>, B<3072>, B<4096>.

=item B<-duration> I<years>

Validity period of the PKI tree in years.

=item B<-num-srk> I<nr>

Number of SRKs to generate.
Must be between 1 and 4.

=item B<-srk-ca> I<yn>

B<y> to generate SRK certificates with the CA flag set.
Such SRK certificates can be used to issue other certificates.

B<n> to generate user certificates.

=item B<--help>

Print help text.

=back

=head1 EXAMPLES

To generate a HAB4 PKI tree with two SRKs

  hab4_pki_tree -existing-ca n -kt rsa -kl 4096 -duration 5 -num-srk 2 -srk-ca y

=head1 SEE ALSO

L<add_key(1)>, L<cst(1)>, L<srktool(1)>, L<config(5ssl)>

=cut
