mirror of
https://github.com/9fans/plan9port.git
synced 2025-01-12 11:10:07 +00:00
254 lines
5 KiB
Groff
254 lines
5 KiB
Groff
.TH RSA 3
|
|
.SH NAME
|
|
asn1dump,
|
|
asn1toRSApriv,
|
|
decodepem,
|
|
decodepemchain,
|
|
rsadecrypt,
|
|
rsaencrypt,
|
|
rsafill,,
|
|
rsagen,
|
|
rsaprivalloc,
|
|
rsaprivfree,
|
|
rsaprivtopub,
|
|
rsapuballoc,
|
|
rsapubfree,
|
|
X509toRSApub,
|
|
X509dump,
|
|
X509gen,
|
|
X509req,
|
|
X509verify \- RSA encryption algorithm
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.br
|
|
.B #include <libc.h>
|
|
.br
|
|
.B #include <mp.h>
|
|
.br
|
|
.B #include <libsec.h>
|
|
.PP
|
|
.B
|
|
.ta +\w'\fLPEMChain* 'u
|
|
RSApriv* rsagen(int nlen, int elen, int nrep)
|
|
.PP
|
|
.B
|
|
RSApriv* rsafill(mpint *n, mpint *ek, mpint *dk, mpint *p, mpint *q)
|
|
.PP
|
|
.B
|
|
mpint* rsaencrypt(RSApub *k, mpint *in, mpint *out)
|
|
.PP
|
|
.B
|
|
mpint* rsadecrypt(RSApriv *k, mpint *in, mpint *out)
|
|
.PP
|
|
.B
|
|
RSApub* rsapuballoc(void)
|
|
.PP
|
|
.B
|
|
void rsapubfree(RSApub*)
|
|
.PP
|
|
.B
|
|
RSApriv* rsaprivalloc(void)
|
|
.PP
|
|
.B
|
|
void rsaprivfree(RSApriv*)
|
|
.PP
|
|
.B
|
|
RSApub* rsaprivtopub(RSApriv*)
|
|
.PP
|
|
.B
|
|
RSApub* X509toRSApub(uchar *cert, int ncert, char *name, int nname)
|
|
.PP
|
|
.B
|
|
RSApriv* asn1toRSApriv(uchar *priv, int npriv)
|
|
.PP
|
|
.B
|
|
void asn1dump(uchar *der, int len)
|
|
.PP
|
|
.B
|
|
uchar* decodepem(char *s, char *type, int *len)
|
|
.PP
|
|
.B
|
|
PEMChain* decodepemchain(char *s, char *type)
|
|
.PP
|
|
.B
|
|
void X509dump(uchar *cert, int ncert)
|
|
.PP
|
|
.B
|
|
uchar* X509gen(RSApriv *priv, char *subj, ulong valid[2], int *certlen);
|
|
.PP
|
|
.B
|
|
uchar* X509req(RSApriv *priv, char *subj, int *certlen);
|
|
.PP
|
|
.B
|
|
char* X509verify(uchar *cert, int ncert, RSApub *pk)
|
|
.SH DESCRIPTION
|
|
.PP
|
|
RSA is a public key encryption algorithm. The owner of a key publishes
|
|
the public part of the key:
|
|
.EX
|
|
struct RSApub
|
|
{
|
|
mpint *n; // modulus
|
|
mpint *ek; // exp (encryption key)
|
|
};
|
|
.EE
|
|
This part can be used for encrypting data (with
|
|
.IR rsaencrypt )
|
|
to be sent to the owner.
|
|
The owner decrypts (with
|
|
.IR rsadecrypt )
|
|
using his private key:
|
|
.EX
|
|
struct RSApriv
|
|
{
|
|
RSApub pub;
|
|
mpint *dk; // exp (decryption key)
|
|
|
|
// precomputed crt values
|
|
mpint *p;
|
|
mpint *q;
|
|
mpint *kp; // k mod p-1
|
|
mpint *kq; // k mod q-1
|
|
mpint *c2; // for converting residues to number
|
|
};
|
|
.EE
|
|
.PP
|
|
Keys are generated using
|
|
.IR rsagen .
|
|
.I Rsagen
|
|
takes both bit length of the modulus, the bit length of the
|
|
public key exponent, and the number of repetitions of the Miller-Rabin
|
|
primality test to run. If the latter is 0, it does the default number
|
|
of rounds.
|
|
.I Rsagen
|
|
returns a newly allocated structure containing both
|
|
public and private keys.
|
|
.I Rsaprivtopub
|
|
returns a newly allocated copy of the public key
|
|
corresponding to the private key.
|
|
.PP
|
|
.I Rsafill
|
|
takes as input the bare minimum pieces of an RSA private key
|
|
and computes the rest
|
|
.RB ( kp ,
|
|
.BR kq ,
|
|
and
|
|
.BR c2 ).
|
|
It returns a new private key.
|
|
All the
|
|
.BR mpint s
|
|
in the key,
|
|
even the ones that correspond directly to
|
|
.IR rsafill 's
|
|
input parameters,
|
|
are freshly allocated,
|
|
.PP
|
|
The routines
|
|
.IR rsaalloc ,
|
|
.IR rsafree ,
|
|
.IR rsapuballoc ,
|
|
.IR rsapubfree ,
|
|
.IR rsaprivalloc ,
|
|
and
|
|
.I rsaprivfree
|
|
are provided to aid in user provided key I/O.
|
|
.PP
|
|
Given a binary X.509
|
|
.IR cert ,
|
|
the routine
|
|
.I X509toRSApub
|
|
returns the public key and, if
|
|
.I name
|
|
is not nil, the CN part of the Distinguished Name of the
|
|
certificate's Subject.
|
|
(This is conventionally a userid or a host DNS name.)
|
|
No verification is done of the certificate signature; the
|
|
caller should check the fingerprint,
|
|
.IR sha1(cert) ,
|
|
against a table or check the certificate by other means.
|
|
X.509 certificates are often stored in PEM format; use
|
|
.I dec64
|
|
to convert to binary before computing the fingerprint or calling
|
|
.IR X509toRSApub .
|
|
For the special case of
|
|
certificates signed by a known trusted key
|
|
(in a single step, without certificate chains)
|
|
.I X509verify
|
|
checks the signature on
|
|
.IR cert .
|
|
It returns nil if successful, else an error string.
|
|
.PP
|
|
.I X509dump
|
|
prints an X.509 certificate to standard ouptut.
|
|
.PP
|
|
.I X509gen
|
|
creates a self-signed X.509 certificate, given an RSA keypair
|
|
.IR priv ,
|
|
a issuer/subject string
|
|
.IR subj ,
|
|
and the starting and ending validity dates,
|
|
.IR valid .
|
|
Length of the allocated binary certificate is stored in
|
|
.IR certlen .
|
|
The subject line is conventionally of the form
|
|
.EX
|
|
"C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric"
|
|
.EE
|
|
using the quoting conventions of
|
|
.I tokenize
|
|
(see
|
|
.MR getfields (3) ).
|
|
.PP
|
|
.I X509req
|
|
creates an X.509 certification request.
|
|
.PP
|
|
.I Asn1toRSApriv
|
|
converts an ASN1 formatted RSA private key into the corresponding
|
|
.B RSApriv
|
|
structure.
|
|
.PP
|
|
.I Asn1dump
|
|
prints an ASN1 object to standard output.
|
|
.PP
|
|
.I Decodepem
|
|
takes a zero terminated string,
|
|
.IR s ,
|
|
and decodes the PEM (privacy-enhanced mail) formatted section for
|
|
.I type
|
|
within it.
|
|
If successful, it returns the decoded section and sets
|
|
.BI * len
|
|
to its decoded length.
|
|
If not, it returns
|
|
.BR nil ,
|
|
and
|
|
.BI * len
|
|
is undefined.
|
|
.PP
|
|
.I Decodepemchain
|
|
is similar but expects a sequence of PEM-formatted sections
|
|
and returns a linked list of the decodings:
|
|
.IP
|
|
.EX
|
|
typedef struct PEMChain PEMChain
|
|
struct PEMChain
|
|
{
|
|
PEMChain *next;
|
|
uchar *pem;
|
|
int pemlen;
|
|
};
|
|
.EE
|
|
.SH SOURCE
|
|
.B \*9/src/libsec
|
|
.SH SEE ALSO
|
|
.MR mp (3) ,
|
|
.MR aes (3) ,
|
|
.MR blowfish (3) ,
|
|
.MR des (3) ,
|
|
.MR dsa (3) ,
|
|
.MR elgamal (3) ,
|
|
.MR rc4 (3) ,
|
|
.MR sechash (3) ,
|
|
.MR prime (3) ,
|
|
.MR rand (3)
|
|
.\" .IR pem (8)
|