Provided by: tcllib_1.19-dfsg-2_all bug

NAME

       pki - Implementation of the public key cipher

SYNOPSIS

       package require Tcl  8.5

       package require pki  ?0.10?

       ::pki::encrypt ?-binary? ?-hex? ?-pad? ?-nopad? ?-priv? ?-pub? ?--? input key

       ::pki::decrypt ?-binary? ?-hex? ?-unpad? ?-nounpad? ?-priv? ?-pub? ?--? input key

       ::pki::sign input key ?algo?

       ::pki::verify signedmessage plaintext key ?algo?

       ::pki::key key ?password? ?encodePem?

       ::pki::pkcs::parse_key key ?password?

       ::pki::x509::parse_cert cert

       ::pki::rsa::generate bitlength ?exponent?

       ::pki::x509::verify_cert cert trustedcerts ?intermediatecerts?

       ::pki::x509::validate_cert    cert    ?-sign_message    dn_of_signer?    ?-encrypt_message
       dn_of_signer? ?-sign_cert dn_to_be_signed ca_depth? ?-ssl dn?

       ::pki::pkcs::create_csr keylist namelist ?encodePem? ?algo?

       ::pki::pkcs::parse_csr csr

       ::pki::x509::create_cert  signreqlist  cakeylist  serial_number  notBefore  notAfter  isCA
       extensions ?encodePem? ?algo?

_________________________________________________________________________________________________

DESCRIPTION

COMMANDS

       ::pki::encrypt ?-binary? ?-hex? ?-pad? ?-nopad? ?-priv? ?-pub? ?--? input key
              Encrypt  a message using PKI (probably RSA).  Requires the caller to specify either
              -priv to encrypt with the private key or -pub to encrypt with the public key.   The
              default  option  is  to  pad  and  return  in  hex.   One  of -pub or -priv must be
              specified.  The -hex option causes  the  data  to  be  returned  in  encoded  as  a
              hexidecimal  string,  while  the -binary option causes the data to be returned as a
              binary string.  If they are specified multiple times, the  last  one  specified  is
              used.   The  -pad  option  causes  the  data to be padded per PKCS#1 prior to being
              encrypted.  The -nopad inhibits this behaviour.  If  they  are  specified  multiple
              times, the last one specified is used.  The input to encrypt is specified as input.
              The key parameter,  holding  the  key  to  use,  is  a  return  value  from  either
              ::pki::pkcs::parse_key, ::pki::x509::parse_cert, or ::pki::rsa::generate.

              Mapping to OpenSSL's openssl application:

              [1]    "openssl rsautl -encrypt" == "::pki::encrypt -binary -pub"

              [2]    "openssl rsautl -sign"    == "::pki::encrypt -binary -priv"

       ::pki::decrypt ?-binary? ?-hex? ?-unpad? ?-nounpad? ?-priv? ?-pub? ?--? input key
              Decrypt a message using PKI (probably RSA). See ::pki::encrypt for option handling.

              Mapping to OpenSSL's openssl application:

              [1]    "openssl rsautl -decrypt" == "::pki::decrypt -binary -priv"

              [2]    "openssl rsautl -verify"  == "::pki::decrypt -binary -pub"

       ::pki::sign input key ?algo?
              Digitally  sign  message input using the private key.  If algo is ommited "sha1" is
              assumed.  Possible values for algo include  "md5",  "sha1",  "sha256",  and  "raw".
              Specifyin  "raw" for algo will inhibit the building of an ASN.1 structure to encode
              which hashing algorithm was chosen.  The input should be the  plain  text,  hashing
              will be performed on it.  The key should include the private key.

       ::pki::verify signedmessage plaintext key ?algo?
              Verify a digital signature using a public key.  Returns true or false.

       ::pki::key key ?password? ?encodePem?
              Convert  a key structure into a serialized PEM (default) or DER encoded private key
              suitable for other applications.  For RSA keys this means PKCS#1.

       ::pki::pkcs::parse_key key ?password?
              Convert a PKCS#1 private key into a usable key, i.e.  one  which  can  be  used  as
              argument for ::pki::encrypt, ::pki::decrypt, ::pki::sign, and ::pki::verify.

       ::pki::x509::parse_cert cert
              Convert  an  X.509 certificate to a usable (public) key, i.e. one which can be used
              as  argument  for  ::pki:encrypt,  ::pki::decrypt,  and  ::pki::verify.   The  cert
              argument can be either PEM or DER encoded.

       ::pki::rsa::generate bitlength ?exponent?
              Generate  a  new  RSA  key  pair,  the  parts  of which can be used as argument for
              ::pki::encrypt, ::pki::decrypt,  ::pki::sign,  and  ::pki::verify.   The  bitlength
              argument  is  the  length  of the public key modulus.  The exponent argument should
              generally not be specified unless you really know what you are doing.

       ::pki::x509::verify_cert cert trustedcerts ?intermediatecerts?
              Verify that a trust can be found between the  certificate  specified  in  the  cert
              argument  and  one of the certificates specified in the list of certificates in the
              trustedcerts argument.  (Eventually the chain can be through untrusted certificates
              listed  in  the  intermediatecerts  argument, but this is currently unimplemented).
              The certificates specified in the cert and trustedcerts  option  should  be  parsed
              (from ::pki::x509::parse_cert).

       ::pki::x509::validate_cert    cert    ?-sign_message    dn_of_signer?    ?-encrypt_message
       dn_of_signer? ?-sign_cert dn_to_be_signed ca_depth? ?-ssl dn?
              Validate that a certificate is valid to be used  in  some  capacity.   If  multiple
              options  are  specified  they  must all be met for this procedure to return "true".
              Currently, only the -sign_cert option is functional.  Arguments for the  -sign_cert
              option  are dn_to_be_signed and ca_depth.  The dn_to_be_signed is the distinguished
              from the subject of a certificate to verify that the certificate specified  in  the
              cert  argument  can sign.  The ca_depth argument is used to indicate at which depth
              the verification should be done at.  Some certificates are limited to how far  down
              the chain they can be used to verify a given certificate.

       ::pki::pkcs::create_csr keylist namelist ?encodePem? ?algo?
              Generate  a  certificate  signing  request from a key pair specified in the keylist
              argument.  The namelist argument is a list of "name" followed by "value"  pairs  to
              encoding  as  the  requested  distinguished  name in the CSR.  The encodePem option
              specifies whether or not the result should be PEM encoded or DER encoded.  A "true"
              value  results  in  the result being PEM encoded, while any other value 9results in
              the the result being DER encoded.  DER encoding is the default.  The algo  argument
              specifies  the  hashing  algorithm  we  should use to sign this certificate signing
              request with.  The default is "sha1".  Other  possible  values  include  "md5"  and
              "sha256".

       ::pki::pkcs::parse_csr csr
              Parse  a  Certificate  Signing  Request.  The csr argument can be either PEM or DER
              encoded.

       ::pki::x509::create_cert  signreqlist  cakeylist  serial_number  notBefore  notAfter  isCA
       extensions ?encodePem? ?algo?
              Sign    a    signing    request    (usually    from    ::pki::pkcs::create_csr   or
              ::pki::pkcs::parse_csr)  with  a  Certificate  Authority  (CA)  certificate.    The
              signreqlist  argument should be the parsed signing request.  The cakeylist argument
              should be the parsed CA certificate.  The serial_number argument should be a serial
              number  unique  to this certificate from this certificate authority.  The notBefore
              and  notAfter  arguments  should  contain  the  time   before   and   after   which
              (respectively)  the  certificate  should be considered invalid.  The time should be
              encoded as something clock format will accept (i.e., the results of  clock  seconds
              and  clock  add).  The isCA argument is a boolean argumen describing whether or not
              the signed certificate should be a a CA certificate.  If specified as true the "id-
              ce-basicConstraints"  extension  is  added  with  the arguments of "critical" being
              true, "allowCA" being true,  and  caDepth  being  -1  (infinite).   The  extensions
              argument  is  a list of extensions and their parameters that should be encoded into
              the created certificate.   Currently only  one  extension  is  understood  ("id-ce-
              basicConstraints").   It  accepts  three  arguments  critical allowCA caDepth.  The
              critical argument to  this  extension  (and  any  extension)  whether  or  not  the
              validator  should  reject  the certificate as invalid if it does not understand the
              extension (if set to "true") or should ignore the extension (if  set  to  "false").
              The allowCA argument is used to specify as a boolean value whether or not we can be
              used a certificate  authority  (CA).   The  caDepth  argument  indicates  how  many
              children  CAs  can  be children of this CA in a depth-wise fashion.  A value of "0"
              for the caDepth argument means that this CA cannot sign a CA certificate  and  have
              the result be valid.  A value of "-1" indicates infinite depth.

EXAMPLES

REFERENCES

       [1]

AUTHORS

       Roy Keene

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.   Please  report  such  in   the   category   rsa   of   the   Tcllib   Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be  made  by going to the Edit form of the ticket immediately after its creation, and then
       using the left-most button in the secondary navigation bar.

SEE ALSO

       aes(3tcl), blowfish(3tcl), des(3tcl), md5(3tcl), sha1(3tcl)

KEYWORDS

       cipher, data integrity, encryption, public key cipher, rsa, security

CATEGORY

       Hashes, checksums, and encryption

COPYRIGHT

       Copyright (c) 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries