sys/man/2/rsa

   1 .TH RSA 2
   2 .SH NAME
   3 asn1dump,
   4 asn1toRSApriv,
   5 decodePEM,
   6 rsadecrypt,
   7 rsaencrypt,
   8 rsafill,
   9 rsagen,
  10 rsaprivalloc,
  11 rsaprivfree,
  12 rsaprivtopub,
  13 rsapuballoc,
  14 rsapubfree,
  15 X509toRSApub,
  16 X509rsagen,
  17 X509rsareq,
  18 X509rsaverify,
  19 X509rsaverifydigest \- RSA encryption algorithm
  20 .SH SYNOPSIS
  21 .B #include <u.h>
  22 .br
  23 .B #include <libc.h>
  24 .br
  25 .B #include <mp.h>
  26 .br
  27 .B #include <libsec.h>
  28 .PP
  29 .ta +\w'\fLRSApriv* \fP'u
  30 .B
  31 RSApriv*        rsagen(int nlen, int elen, int nrep)
  32 .PP
  33 .ta +\w'\fLRSApriv* \fP'u
  34 .B
  35 RSApriv*        rsafill(mpint *n, mpint *e, mpint *d, 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, char **new_s)
  69 .PP
  70 .B
  71 uchar*  X509rsagen(RSApriv *priv, char *subj, ulong valid[2], int *certlen);
  72 .PP
  73 .B
  74 uchar*  X509rsareq(RSApriv *priv, char *subj, int *certlen);
  75 .PP
  76 .B
  77 char*   X509rsaverify(uchar *cert, int ncert, RSApub *pk)
  78 .PP
  79 .B
  80 char*   X509rsaverifydigest(uchar *sig, int siglen, uchar *edigest, int edigestlen, RSApub *pk)
  81 .DT
  82 .SH DESCRIPTION
  83 RSA is a public key encryption algorithm.  The owner of a key publishes
  84 the public part of the key:
  85 .IP
  86 .EX
  87 struct RSApub
  88 {
  89         mpint   *n;     /* modulus */
  90         mpint   *ek;    /* exp (encryption key) */
  91 };
  92 .EE
  93 .LP
  94 This part can be used for encrypting data (with
  95 .IR rsaencrypt )
  96 to be sent to the owner.
  97 The owner decrypts (with
  98 .IR rsadecrypt )
  99 using his private key:
 100 .IP
 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 Rsafill
 127 returns a newly allocated private key by recomputing
 128 .IR kp ,
 129 .IR kq ,
 130 and
 131 .IR c2 .
 132 .I Rsaprivtopub
 133 returns a newly allocated copy of the public key
 134 corresponding to the private key.
 135 .PP
 136 The routines
 137 .IR rsaalloc ,
 138 .IR rsafree ,
 139 .IR rsapuballoc ,
 140 .IR rsapubfree ,
 141 .IR rsaprivalloc ,
 142 and
 143 .I rsaprivfree
 144 are provided to aid in user provided key I/O.
 145 .PP
 146 Given a binary X.509
 147 .IR cert ,
 148 the routine
 149 .I X509toRSApub
 150 returns the public key and, if
 151 .I name
 152 is not
 153 .BR nil ,
 154 the CN part of the Distinguished Name of the
 155 certificate's Subject.
 156 (This is conventionally a userid or a host DNS name.)
 157 No verification is done of the certificate signature;  the
 158 caller should check the fingerprint,
 159 .IR sha1(cert) ,
 160 against a table or check the certificate by other means.
 161 X.509 certificates are often stored in PEM format; use
 162 .I dec64
 163 to convert to binary before computing the fingerprint or calling
 164 .IR X509toRSApub .
 165 For the special case of
 166 certificates signed by a known trusted key
 167 (in a single step, without certificate chains),
 168 .I X509rsaverify
 169 checks the signature on
 170 .IR cert .
 171 It returns
 172 .B nil
 173 if successful, else an error string.
 174 .PP
 175 .I X509rsaverifydigest
 176 takes a encoded PKCS #1 signature as used in X.509 as
 177 .IR sig [ siglen ]
 178 and verifies it against the expected cryptographic hash
 179 .IR edigest [ edigestlen ]
 180 of the signed data;
 181 returning
 182 .B nil
 183 on success or an error string.
 184 .PP
 185 .I X509rsagen
 186 creates a self-signed X.509 certificate, given an RSA keypair
 187 .IR priv ,
 188 a issuer/subject string
 189 .IR subj ,
 190 and the starting and ending validity dates,
 191 .IR valid .
 192 Length of the allocated binary certificate is stored in
 193 .IR certlen .
 194 The subject line is conventionally of the form
 195 .IP
 196 .EX
 197 C=US ST=NJ L=07922 O=Lucent OU='Bell Labs' CN=Eric
 198 .EE
 199 .LP
 200 using the quoting conventions of
 201 .I tokenize
 202 in
 203 .IR getfields (2).
 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
 220 .IR malloc ed
 221 storage containing the decoded section,
 222 which the caller must free,
 223 and sets
 224 .BI * len
 225 to its decoded length.
 226 Otherwise
 227 .B nil
 228 is returned and
 229 .BI * len
 230 is undefined.
 231 If not
 232 .BR nil ,
 233 .I new_s
 234 is set to the first character beyond the
 235 .I type
 236 section.
 237 .SH SOURCE
 238 .B /sys/src/libsec
 239 .SH SEE ALSO
 240 .IR mp (2),
 241 .IR aes (2),
 242 .IR blowfish (2),
 243 .IR des (2),
 244 .IR dsa (2),
 245 .IR elgamal (2),
 246 .IR rc4 (2),
 247 .IR sechash (2),
 248 .IR prime (2),
 249 .IR rand (2),
 250 .IR rsa (8)