sys/man/2/rsa

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