rsa.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)