docs/pythondoc-cert.html

   1 <!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
   2 <html>
   3 <head>
   4 <meta http-equiv='Content-Type' content='text/html; charset=us-ascii' />
   5 <title>The cert Module</title>
   6 </head>
   7 <body>
   8 <h1>The cert Module</h1>
   9 <p>Geniwrapper uses two crypto libraries: pyOpenSSL and M2Crypto to implement
  10 the necessary crypto functionality. Ideally just one of these libraries
  11 would be used, but unfortunately each of these libraries is independently
  12 lacking. The pyOpenSSL library is missing many necessary functions, and
  13 the M2Crypto library has crashed inside of some of the functions. The
  14 design decision is to use pyOpenSSL whenever possible as it seems more
  15 stable, and only use M2Crypto for those functions that are not possible
  16 in pyOpenSSL.
  17
  18 This module exports two classes: Keypair and Certificate.</p>
  19 <dl>
  20 <dt><b>Certificate(create=False, subject=None, string=None, filename=None)</b> (class) [<a href='#cert.Certificate-class'>#</a>]</dt>
  21 <dd>
  22 <p>The certificate class implements a general purpose X509 certificate, making
  23 use of the appropriate pyOpenSSL or M2Crypto abstractions.</p>
  24 <p>For more information about this class, see <a href='#cert.Certificate-class'><i>The Certificate Class</i></a>.</p>
  25 </dd>
  26 <dt><b>Keypair(create=False, string=None, filename=None)</b> (class) [<a href='#cert.Keypair-class'>#</a>]</dt>
  27 <dd>
  28 <p>Public-private key pairs are implemented by the Keypair class.</p>
  29 <p>For more information about this class, see <a href='#cert.Keypair-class'><i>The Keypair Class</i></a>.</p>
  30 </dd>
  31 </dl>
  32 <h2><a id='cert.Certificate-class' name='cert.Certificate-class'>The Certificate Class</a></h2>
  33 <dl>
  34 <dt><b>Certificate(create=False, subject=None, string=None, filename=None)</b> (class) [<a href='#cert.Certificate-class'>#</a>]</dt>
  35 <dd>
  36 <p>The certificate class implements a general purpose X509 certificate, making
  37 use of the appropriate pyOpenSSL or M2Crypto abstractions. It also adds
  38 several addition features, such as the ability to maintain a chain of
  39 parent certificates, and storage of application-specific data.
  40
  41 Certificates include the ability to maintain a chain of parents. Each
  42 certificate includes a pointer to it's parent certificate. When loaded
  43 from a file or a string, the parent chain will be automatically loaded.
  44 When saving a certificate to a file or a string, the caller can choose
  45 whether to save the parent certificates as well.</p>
  46 </dd>
  47 <dt><a id='cert.Certificate.__init__-method' name='cert.Certificate.__init__-method'><b>__init__(create=False, subject=None, string=None, filename=None)</b></a> [<a href='#cert.Certificate.__init__-method'>#</a>]</dt>
  48 <dd>
  49 <p>Create a certificate object.</p>
  50 <dl>
  51 <dt><i>create</i></dt>
  52 <dd>
  53 If create==True, then also create a blank X509 certificate.</dd>
  54 <dt><i>subject</i></dt>
  55 <dd>
  56 If subject!=None, then create a blank certificate and set
  57     it's subject name.</dd>
  58 <dt><i>string</i></dt>
  59 <dd>
  60 If string!=None, load the certificate from the string.</dd>
  61 <dt><i>filename</i></dt>
  62 <dd>
  63 If filename!=None, load the certificate from the file.</dd>
  64 </dl><br />
  65 </dd>
  66 <dt><a id='cert.Certificate.add_extension-method' name='cert.Certificate.add_extension-method'><b>add_extension(name, critical, value)</b></a> [<a href='#cert.Certificate.add_extension-method'>#</a>]</dt>
  67 <dd>
  68 <p>Add an X509 extension to the certificate. Add_extension can only be called
  69 once for a particular extension name, due to limitations in the underlying
  70 library.</p>
  71 <dl>
  72 <dt><i>name</i></dt>
  73 <dd>
  74 string containing name of extension</dd>
  75 <dt><i>value</i></dt>
  76 <dd>
  77 string containing value of the extension</dd>
  78 </dl><br />
  79 </dd>
  80 <dt><a id='cert.Certificate.create-method' name='cert.Certificate.create-method'><b>create()</b></a> [<a href='#cert.Certificate.create-method'>#</a>]</dt>
  81 <dd>
  82 <p>Create a blank X509 certificate and store it in this object.</p>
  83 </dd>
  84 <dt><a id='cert.Certificate.get_data-method' name='cert.Certificate.get_data-method'><b>get_data()</b></a> [<a href='#cert.Certificate.get_data-method'>#</a>]</dt>
  85 <dd>
  86 <p>Return the data string that was previously set with set_data</p>
  87 </dd>
  88 <dt><a id='cert.Certificate.get_extension-method' name='cert.Certificate.get_extension-method'><b>get_extension(name)</b></a> [<a href='#cert.Certificate.get_extension-method'>#</a>]</dt>
  89 <dd>
  90 <p>Get an X509 extension from the certificate</p>
  91 </dd>
  92 <dt><a id='cert.Certificate.get_issuer-method' name='cert.Certificate.get_issuer-method'><b>get_issuer(which=&quot;CN&quot;)</b></a> [<a href='#cert.Certificate.get_issuer-method'>#</a>]</dt>
  93 <dd>
  94 <p>Get the issuer name</p>
  95 </dd>
  96 <dt><a id='cert.Certificate.get_parent-method' name='cert.Certificate.get_parent-method'><b>get_parent()</b></a> [<a href='#cert.Certificate.get_parent-method'>#</a>]</dt>
  97 <dd>
  98 <p>Return the certificate object of the parent of this certificate.</p>
  99 </dd>
 100 <dt><a id='cert.Certificate.get_pubkey-method' name='cert.Certificate.get_pubkey-method'><b>get_pubkey()</b></a> [<a href='#cert.Certificate.get_pubkey-method'>#</a>]</dt>
 101 <dd>
 102 <p>Get the public key of the certificate.
 103 It is returned in the form of a Keypair object.</p>
 104 </dd>
 105 <dt><a id='cert.Certificate.get_subject-method' name='cert.Certificate.get_subject-method'><b>get_subject(which=&quot;CN&quot;)</b></a> [<a href='#cert.Certificate.get_subject-method'>#</a>]</dt>
 106 <dd>
 107 <p>Get the subject name of the certificate</p>
 108 </dd>
 109 <dt><a id='cert.Certificate.is_pubkey-method' name='cert.Certificate.is_pubkey-method'><b>is_pubkey(pkey)</b></a> [<a href='#cert.Certificate.is_pubkey-method'>#</a>]</dt>
 110 <dd>
 111 <p>Return True if pkey is identical to the public key that is contained in the certificate.</p>
 112 <dl>
 113 <dt><i>pkey</i></dt>
 114 <dd>
 115 Keypair object</dd>
 116 </dl><br />
 117 </dd>
 118 <dt><a id='cert.Certificate.is_signed_by_cert-method' name='cert.Certificate.is_signed_by_cert-method'><b>is_signed_by_cert(cert)</b></a> [<a href='#cert.Certificate.is_signed_by_cert-method'>#</a>]</dt>
 119 <dd>
 120 <p>Given a certificate cert, verify that this certificate was signed by the
 121 public key contained in cert. Throw an exception otherwise.</p>
 122 <dl>
 123 <dt><i>cert</i></dt>
 124 <dd>
 125 certificate object</dd>
 126 </dl><br />
 127 </dd>
 128 <dt><a id='cert.Certificate.load_from_file-method' name='cert.Certificate.load_from_file-method'><b>load_from_file(filename)</b></a> [<a href='#cert.Certificate.load_from_file-method'>#</a>]</dt>
 129 <dd>
 130 <p>Load the certificate from a file</p>
 131 </dd>
 132 <dt><a id='cert.Certificate.load_from_pyopenssl_x509-method' name='cert.Certificate.load_from_pyopenssl_x509-method'><b>load_from_pyopenssl_x509(x509)</b></a> [<a href='#cert.Certificate.load_from_pyopenssl_x509-method'>#</a>]</dt>
 133 <dd>
 134 <p>Given a pyOpenSSL X509 object, store that object inside of this
 135 certificate object.</p>
 136 </dd>
 137 <dt><a id='cert.Certificate.load_from_string-method' name='cert.Certificate.load_from_string-method'><b>load_from_string(string)</b></a> [<a href='#cert.Certificate.load_from_string-method'>#</a>]</dt>
 138 <dd>
 139 <p>Load the certificate from a string</p>
 140 </dd>
 141 <dt><a id='cert.Certificate.save_to_file-method' name='cert.Certificate.save_to_file-method'><b>save_to_file(filename, save_parents=False)</b></a> [<a href='#cert.Certificate.save_to_file-method'>#</a>]</dt>
 142 <dd>
 143 <p>Save the certificate to a file.</p>
 144 <dl>
 145 <dt><i>save_parents</i></dt>
 146 <dd>
 147 If save_parents==True, then also save the parent certificates.</dd>
 148 </dl><br />
 149 </dd>
 150 <dt><a id='cert.Certificate.save_to_string-method' name='cert.Certificate.save_to_string-method'><b>save_to_string(save_parents=False)</b></a> [<a href='#cert.Certificate.save_to_string-method'>#</a>]</dt>
 151 <dd>
 152 <p>Save the certificate to a string.</p>
 153 <dl>
 154 <dt><i>save_parents</i></dt>
 155 <dd>
 156 If save_parents==True, then also save the parent certificates.</dd>
 157 </dl><br />
 158 </dd>
 159 <dt><a id='cert.Certificate.set_data-method' name='cert.Certificate.set_data-method'><b>set_data(str)</b></a> [<a href='#cert.Certificate.set_data-method'>#</a>]</dt>
 160 <dd>
 161 <p>Set_data is a wrapper around add_extension. It stores the parameter str in
 162 the X509 subject_alt_name extension. Set_data can only be called once, due
 163 to limitations in the underlying library.</p>
 164 </dd>
 165 <dt><a id='cert.Certificate.set_issuer-method' name='cert.Certificate.set_issuer-method'><b>set_issuer(key, subject=None, cert=None)</b></a> [<a href='#cert.Certificate.set_issuer-method'>#</a>]</dt>
 166 <dd>
 167 <p>Sets the issuer private key and name</p>
 168 <dl>
 169 <dt><i>key</i></dt>
 170 <dd>
 171 Keypair object containing the private key of the issuer</dd>
 172 <dt><i>subject</i></dt>
 173 <dd>
 174 String containing the name of the issuer</dd>
 175 <dt><i>cert</i></dt>
 176 <dd>
 177 (optional) Certificate object containing the name of the issuer</dd>
 178 </dl><br />
 179 </dd>
 180 <dt><a id='cert.Certificate.set_parent-method' name='cert.Certificate.set_parent-method'><b>set_parent(p)</b></a> [<a href='#cert.Certificate.set_parent-method'>#</a>]</dt>
 181 <dd>
 182 <p>Set the parent certificate.</p>
 183 <dl>
 184 <dt><i>p</i></dt>
 185 <dd>
 186 certificate object.</dd>
 187 </dl><br />
 188 </dd>
 189 <dt><a id='cert.Certificate.set_pubkey-method' name='cert.Certificate.set_pubkey-method'><b>set_pubkey(key)</b></a> [<a href='#cert.Certificate.set_pubkey-method'>#</a>]</dt>
 190 <dd>
 191 <p>Get the public key of the certificate.</p>
 192 <dl>
 193 <dt><i>key</i></dt>
 194 <dd>
 195 Keypair object containing the public key</dd>
 196 </dl><br />
 197 </dd>
 198 <dt><a id='cert.Certificate.set_subject-method' name='cert.Certificate.set_subject-method'><b>set_subject(name)</b></a> [<a href='#cert.Certificate.set_subject-method'>#</a>]</dt>
 199 <dd>
 200 <p>Set the subject name of the certificate</p>
 201 </dd>
 202 <dt><a id='cert.Certificate.sign-method' name='cert.Certificate.sign-method'><b>sign()</b></a> [<a href='#cert.Certificate.sign-method'>#</a>]</dt>
 203 <dd>
 204 <p>Sign the certificate using the issuer private key and issuer subject previous set with set_issuer().</p>
 205 </dd>
 206 <dt><a id='cert.Certificate.verify-method' name='cert.Certificate.verify-method'><b>verify(pkey)</b></a> [<a href='#cert.Certificate.verify-method'>#</a>]</dt>
 207 <dd>
 208 <p>Verify the authenticity of a certificate.</p>
 209 <dl>
 210 <dt><i>pkey</i></dt>
 211 <dd>
 212 is a Keypair object representing a public key. If Pkey
 213     did not sign the certificate, then an exception will be thrown.</dd>
 214 </dl><br />
 215 </dd>
 216 <dt><a id='cert.Certificate.verify_chain-method' name='cert.Certificate.verify_chain-method'><b>verify_chain(trusted_certs=None)</b></a> [<a href='#cert.Certificate.verify_chain-method'>#</a>]</dt>
 217 <dd>
 218 <p>Verification examines a chain of certificates to ensure that each parent
 219 signs the child, and that some certificate in the chain is signed by a
 220 trusted certificate.
 221
 222 Verification is a basic recursion: <pre>
 223     if this_certificate was signed by trusted_certs:
 224         return
 225     else
 226         return verify_chain(parent, trusted_certs)
 227 </pre>
 228
 229 At each recursion, the parent is tested to ensure that it did sign the
 230 child. If a parent did not sign a child, then an exception is thrown. If
 231 the bottom of the recursion is reached and the certificate does not match
 232 a trusted root, then an exception is thrown.
 233
 234 </p><dl>
 235 <dt><i>Trusted_certs</i></dt>
 236 <dd>
 237 is a list of certificates that are trusted.</dd>
 238 </dl><br />
 239 </dd>
 240 </dl>
 241 <h2><a id='cert.Keypair-class' name='cert.Keypair-class'>The Keypair Class</a></h2>
 242 <dl>
 243 <dt><b>Keypair(create=False, string=None, filename=None)</b> (class) [<a href='#cert.Keypair-class'>#</a>]</dt>
 244 <dd>
 245 <p>Public-private key pairs are implemented by the Keypair class.
 246 A Keypair object may represent both a public and private key pair, or it
 247 may represent only a public key (this usage is consistent with OpenSSL).</p>
 248 </dd>
 249 <dt><a id='cert.Keypair.__init__-method' name='cert.Keypair.__init__-method'><b>__init__(create=False, string=None, filename=None)</b></a> [<a href='#cert.Keypair.__init__-method'>#</a>]</dt>
 250 <dd>
 251 <p>Creates a Keypair object</p>
 252 <dl>
 253 <dt><i>create</i></dt>
 254 <dd>
 255 If create==True, creates a new public/private key and
 256     stores it in the object</dd>
 257 <dt><i>string</i></dt>
 258 <dd>
 259 If string!=None, load the keypair from the string (PEM)</dd>
 260 <dt><i>filename</i></dt>
 261 <dd>
 262 If filename!=None, load the keypair from the file</dd>
 263 </dl><br />
 264 </dd>
 265 <dt><a id='cert.Keypair.as_pem-method' name='cert.Keypair.as_pem-method'><b>as_pem()</b></a> [<a href='#cert.Keypair.as_pem-method'>#</a>]</dt>
 266 <dd>
 267 <p>Return the private key in PEM format.</p>
 268 </dd>
 269 <dt><a id='cert.Keypair.create-method' name='cert.Keypair.create-method'><b>create()</b></a> [<a href='#cert.Keypair.create-method'>#</a>]</dt>
 270 <dd>
 271 <p>Create a RSA public/private key pair and store it inside the keypair object</p>
 272 </dd>
 273 <dt><a id='cert.Keypair.get_m2_pkey-method' name='cert.Keypair.get_m2_pkey-method'><b>get_m2_pkey()</b></a> [<a href='#cert.Keypair.get_m2_pkey-method'>#</a>]</dt>
 274 <dd>
 275 <p>Return an OpenSSL pkey object</p>
 276 </dd>
 277 <dt><a id='cert.Keypair.get_openssl_pkey-method' name='cert.Keypair.get_openssl_pkey-method'><b>get_openssl_pkey()</b></a> [<a href='#cert.Keypair.get_openssl_pkey-method'>#</a>]</dt>
 278 <dd>
 279 <p>Given another Keypair object, return TRUE if the two keys are the same.</p>
 280 </dd>
 281 <dt><a id='cert.Keypair.load_from_file-method' name='cert.Keypair.load_from_file-method'><b>load_from_file(filename)</b></a> [<a href='#cert.Keypair.load_from_file-method'>#</a>]</dt>
 282 <dd>
 283 <p>Load the private key from a file. Implicity the private key includes the public key.</p>
 284 </dd>
 285 <dt><a id='cert.Keypair.load_from_string-method' name='cert.Keypair.load_from_string-method'><b>load_from_string(string)</b></a> [<a href='#cert.Keypair.load_from_string-method'>#</a>]</dt>
 286 <dd>
 287 <p>Load the private key from a string. Implicitly the private key includes the public key.</p>
 288 </dd>
 289 <dt><a id='cert.Keypair.load_pubkey_from_file-method' name='cert.Keypair.load_pubkey_from_file-method'><b>load_pubkey_from_file(filename)</b></a> [<a href='#cert.Keypair.load_pubkey_from_file-method'>#</a>]</dt>
 290 <dd>
 291 <p>Load the public key from a string. No private key is loaded.</p>
 292 </dd>
 293 <dt><a id='cert.Keypair.load_pubkey_from_string-method' name='cert.Keypair.load_pubkey_from_string-method'><b>load_pubkey_from_string(string)</b></a> [<a href='#cert.Keypair.load_pubkey_from_string-method'>#</a>]</dt>
 294 <dd>
 295 <p>Load the public key from a string. No private key is loaded.</p>
 296 </dd>
 297 <dt><a id='cert.Keypair.save_to_file-method' name='cert.Keypair.save_to_file-method'><b>save_to_file(filename)</b></a> [<a href='#cert.Keypair.save_to_file-method'>#</a>]</dt>
 298 <dd>
 299 <p>Save the private key to a file</p>
 300 <dl>
 301 <dt><i>filename</i></dt>
 302 <dd>
 303 name of file to store the keypair in</dd>
 304 </dl><br />
 305 </dd>
 306 </dl>
 307 </body></html>