10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
255 lines
4.9 KiB
Groff
255 lines
4.9 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)
|