pki(n)                     RSA public key encryption                    pki(n)



______________________________________________________________________________

NAME
       pki - Implementation of the RSA public key cipher

SYNOPSIS
       package require Tcl  8.5

       package require pki  ?0.2?

       ::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::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::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 SF Trackers [http://sourceforge.net/tracker/?group_id=12883].
       Please also report any ideas for enhancements you may have for either
       package and/or documentation.

SEE ALSO
       aes(n), blowfish(n), des(n), md5(n), sha1(n)

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

CATEGORY
       Hashes, checksums, and encryption

COPYRIGHT
       Copyright (c) 2010, Roy Keene




pki                                   0.2                               pki(n)
