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(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, Roy Keene