trsa.3 - plan9port - [fork] Plan 9 from user space
HTML git clone git://src.adamsgaard.dk/plan9port
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
trsa.3 (5070B)
---
1 .TH RSA 3
2 .SH NAME
3 asn1dump,
4 asn1toRSApriv,
5 decodepem,
6 decodepemchain,
7 rsadecrypt,
8 rsaencrypt,
9 rsafill,,
10 rsagen,
11 rsaprivalloc,
12 rsaprivfree,
13 rsaprivtopub,
14 rsapuballoc,
15 rsapubfree,
16 X509toRSApub,
17 X509dump,
18 X509gen,
19 X509req,
20 X509verify \- RSA encryption algorithm
21 .SH SYNOPSIS
22 .B #include <u.h>
23 .br
24 .B #include <libc.h>
25 .br
26 .B #include <mp.h>
27 .br
28 .B #include <libsec.h>
29 .PP
30 .B
31 .ta +\w'\fLPEMChain* 'u
32 RSApriv* rsagen(int nlen, int elen, int nrep)
33 .PP
34 .B
35 RSApriv* rsafill(mpint *n, mpint *ek, mpint *dk, mpint *p, mpint *q)
36 .PP
37 .B
38 mpint* rsaencrypt(RSApub *k, mpint *in, mpint *out)
39 .PP
40 .B
41 mpint* rsadecrypt(RSApriv *k, mpint *in, mpint *out)
42 .PP
43 .B
44 RSApub* rsapuballoc(void)
45 .PP
46 .B
47 void rsapubfree(RSApub*)
48 .PP
49 .B
50 RSApriv* rsaprivalloc(void)
51 .PP
52 .B
53 void rsaprivfree(RSApriv*)
54 .PP
55 .B
56 RSApub* rsaprivtopub(RSApriv*)
57 .PP
58 .B
59 RSApub* X509toRSApub(uchar *cert, int ncert, char *name, int nname)
60 .PP
61 .B
62 RSApriv* asn1toRSApriv(uchar *priv, int npriv)
63 .PP
64 .B
65 void asn1dump(uchar *der, int len)
66 .PP
67 .B
68 uchar* decodepem(char *s, char *type, int *len)
69 .PP
70 .B
71 PEMChain* decodepemchain(char *s, char *type)
72 .PP
73 .B
74 void X509dump(uchar *cert, int ncert)
75 .PP
76 .B
77 uchar* X509gen(RSApriv *priv, char *subj, ulong valid[2], int *certlen);
78 .PP
79 .B
80 uchar* X509req(RSApriv *priv, char *subj, int *certlen);
81 .PP
82 .B
83 char* X509verify(uchar *cert, int ncert, RSApub *pk)
84 .SH DESCRIPTION
85 .PP
86 RSA is a public key encryption algorithm. The owner of a key publishes
87 the public part of the key:
88 .EX
89 struct RSApub
90 {
91 mpint *n; // modulus
92 mpint *ek; // exp (encryption key)
93 };
94 .EE
95 This part can be used for encrypting data (with
96 .IR rsaencrypt )
97 to be sent to the owner.
98 The owner decrypts (with
99 .IR rsadecrypt )
100 using his private key:
101 .EX
102 struct RSApriv
103 {
104 RSApub pub;
105 mpint *dk; // exp (decryption key)
106
107 // precomputed crt values
108 mpint *p;
109 mpint *q;
110 mpint *kp; // k mod p-1
111 mpint *kq; // k mod q-1
112 mpint *c2; // for converting residues to number
113 };
114 .EE
115 .PP
116 Keys are generated using
117 .IR rsagen .
118 .I Rsagen
119 takes both bit length of the modulus, the bit length of the
120 public key exponent, and the number of repetitions of the Miller-Rabin
121 primality test to run. If the latter is 0, it does the default number
122 of rounds.
123 .I Rsagen
124 returns a newly allocated structure containing both
125 public and private keys.
126 .I Rsaprivtopub
127 returns a newly allocated copy of the public key
128 corresponding to the private key.
129 .PP
130 .I Rsafill
131 takes as input the bare minimum pieces of an RSA private key
132 and computes the rest
133 .RB ( kp ,
134 .BR kq ,
135 and
136 .BR c2 ).
137 It returns a new private key.
138 All the
139 .BR mpint s
140 in the key,
141 even the ones that correspond directly to
142 .IR rsafill 's
143 input parameters,
144 are freshly allocated,
145 .PP
146 The routines
147 .IR rsaalloc ,
148 .IR rsafree ,
149 .IR rsapuballoc ,
150 .IR rsapubfree ,
151 .IR rsaprivalloc ,
152 and
153 .I rsaprivfree
154 are provided to aid in user provided key I/O.
155 .PP
156 Given a binary X.509
157 .IR cert ,
158 the routine
159 .I X509toRSApub
160 returns the public key and, if
161 .I name
162 is not nil, the CN part of the Distinguished Name of the
163 certificate's Subject.
164 (This is conventionally a userid or a host DNS name.)
165 No verification is done of the certificate signature; the
166 caller should check the fingerprint,
167 .IR sha1(cert) ,
168 against a table or check the certificate by other means.
169 X.509 certificates are often stored in PEM format; use
170 .I dec64
171 to convert to binary before computing the fingerprint or calling
172 .IR X509toRSApub .
173 For the special case of
174 certificates signed by a known trusted key
175 (in a single step, without certificate chains)
176 .I X509verify
177 checks the signature on
178 .IR cert .
179 It returns nil if successful, else an error string.
180 .PP
181 .I X509dump
182 prints an X.509 certificate to standard ouptut.
183 .PP
184 .I X509gen
185 creates a self-signed X.509 certificate, given an RSA keypair
186 .IR priv ,
187 a issuer/subject string
188 .IR subj ,
189 and the starting and ending validity dates,
190 .IR valid .
191 Length of the allocated binary certificate is stored in
192 .IR certlen .
193 The subject line is conventionally of the form
194 .EX
195 "C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric"
196 .EE
197 using the quoting conventions of
198 .I tokenize
199 (see
200 .MR getfields (3) ).
201 .PP
202 .I X509req
203 creates an X.509 certification request.
204 .PP
205 .I Asn1toRSApriv
206 converts an ASN1 formatted RSA private key into the corresponding
207 .B RSApriv
208 structure.
209 .PP
210 .I Asn1dump
211 prints an ASN1 object to standard output.
212 .PP
213 .I Decodepem
214 takes a zero terminated string,
215 .IR s ,
216 and decodes the PEM (privacy-enhanced mail) formatted section for
217 .I type
218 within it.
219 If successful, it returns the decoded section and sets
220 .BI * len
221 to its decoded length.
222 If not, it returns
223 .BR nil ,
224 and
225 .BI * len
226 is undefined.
227 .PP
228 .I Decodepemchain
229 is similar but expects a sequence of PEM-formatted sections
230 and returns a linked list of the decodings:
231 .IP
232 .EX
233 typedef struct PEMChain PEMChain
234 struct PEMChain
235 {
236 PEMChain *next;
237 uchar *pem;
238 int pemlen;
239 };
240 .EE
241 .SH SOURCE
242 .B \*9/src/libsec
243 .SH SEE ALSO
244 .MR mp (3) ,
245 .MR aes (3) ,
246 .MR blowfish (3) ,
247 .MR des (3) ,
248 .MR dsa (3) ,
249 .MR elgamal (3) ,
250 .MR rc4 (3) ,
251 .MR sechash (3) ,
252 .MR prime (3) ,
253 .MR rand (3)
254 .\" .IR pem (8)