pki - Implementation of the public key cipher
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?
- ::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.
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.
cipher, data integrity, encryption, public key cipher, rsa,
security
Hashes, checksums, and encryption
Copyright (c) 2010, 2011, 2012, 2013, Roy Keene, Andreas Kupries