pki(3tcl) public key encryption pki(3tcl)
______________________________________________________________________________
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? ?--? in-
put 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? ?-en-
crypt_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? ?--? in-
put 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 hex-
idecimal 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".
Specifying "raw" for algo will inhibit the building of an ASN.1
structure to encode which hashing algorithm was chosen. Atten-
tion: In this case the corresponding pkgi::verify must be called
with algorithm information. Conversely, specifying a non-"raw"
algorithm here means that the corresponding pkgi::verify invoka-
tion has to be made without algorithm information.
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.
Attention: The algorithm information algo has to be specified if
and only if the pki::sign which generated the signedmessage was
called with algorithm "raw". This inhibited the building of the
ASN.1 structure encoding the chosen hashing algorithm. Con-
versely, if a proper algorithm was specified during signing then
you must not specify an algorithm here.
::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 pub-
lic 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 speci-
fied 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? ?-en-
crypt_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 capac-
ity. 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 dis-
tinguished 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 verifi-
cation should be done at. Some certificates are limited to how
far down the chain they can be used to verify a given certifi-
cate.
::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 in-
clude "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) cer-
tificate. The signreqlist argument should be the parsed signing
request. The cakeylist argument should be the parsed CA cer-
tificate. 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 consid-
ered 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" be-
ing true, and caDepth being -1 (infinite). The extensions argu-
ment is a list of extensions and their parameters that should be
encoded into the created certificate. Currently only one ex-
tension 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 valida-
tor should reject the certificate as invalid if it does not un-
derstand 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 cer-
tificate 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 out-
put 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
tcllib 0.10 pki(3tcl)